From cosign wiki

(Difference between revisions)

Jump to: navigation, search

Revision as of 11:38, 16 November 2006

Building and Installing the Cosign Apache Filter

Requirements

The Cosign Apache filter requires:

Apache v1.3.x or v2.x
OpenSSL v0.9.7a or newer
A source of entropy for the OpenSSL libraries.
If your system already has /dev/*random, then you're all set; otherwise, look into installing prngd or egd.
Solaris users should refer to Sun document 27606, "Differing /dev/random support requirements within Solaris [TM] Operating Environments", at http://sunsolve.sun.com. Users of operating systems lacking a built-in source of entropy, such as AIX, will want to get prngd.
MIT Kerberos krb5-1.2.7 or later (optional, for protected services that require Kerberos credentials)
Kerberos libraries are not required if you do not need access to Kerberos credentials.
If you are building a central weblogin server, see the Cosign weblogin README.
mod_ssl (more information is needed here)

Build Configuration Options

./configure may take the following options:

--enable-krb=path_to_krb                enables Kerberos V
--enable-apache1=path_to_apxs_1.3       enables Apache 1.3 filter
--enable-apache2=path_to_apxs_2         enables Apache 2 filter
--with-GSS                              enables GSSAPI
--with-filterdb=DIR                     overrides default of /var/cosign/filter

Building for Red Hat 9

In Red Hat Linux 9, Kerberos is in a non-standard place. configure may not find it by default.

Before before running configure, prepend env CPPFLAGS=-I/usr/kerberos/include to the command.

In csh, configure should resemble the following:

env CPPFLAGS="-I/usr/kerberos/include" ./configure

In bash or sh, configure should resemble the following:

CPPFLAGS="-I/usr/kerberos/include" ./configure

Including APR Flags

In some cases, a configure attempt may fail with "file not found" errors related to Apache Portable Runtime (APR) headers, such as the following:

/usr/include/httpd/ap_config.h:19:17: apr.h: No such file or directory

To remedy this error, prepend a CPPFLAGS parameter to locate the APR headers for apxs.

In csh:

env CPPFLAGS="-I/usr/include/apr-0/" ./configure

In bash or sh:

CPPFLAGS="-I/usr/include/apr-0/" ./configure

Building and Installing the Filter

1) Configure the build with any required flags and options:

./configure [options]

2) Make the build:

make

3) Install the the filter (using your copy of apxs):

make install

4) Create a Cosign filter directory:

mkdir -p /var/cosign/filter

5) Set ownership for the a Cosign filter directory. Be sure to change APACHE_USER to the username defined in your httpd.conf file.

chown APACHE_USER /var/cosign/filter

6) Create a CA directory to store your CA certificates.

mkdir -p /usr/local/etc/apache/certs

7) Copy the CAs from the Cosign source distribution CAcerts directory to your CA dir:

cp CAcerts/* /usr/local/etc/apache/certs

8) Issue the c_rehash command, which is a perl script that ships with OpenSSL. Assuming a CA directory of /usr/local/etc/apache/certs, the command would be:

c_rehash /usr/local/etc/apache/certs

The output should resemble the following:

Doing /usr/local/etc/apache/certs
    umwebCA.pem => 4700e8dd.0
    RSA-SSCA.pem => f73e89fd.0
    entrust.pem => ed524cf5.0

Configuring Apache

Apache Configuration Options

mod_cosign recognizes the following Apache configuration directives:

CosignHostname

The name of the host running cosignd.

Syntax: CosignHostname fully-qualified-domain-name
Default: cosign.example.edu
Server configuration context: VirtualHost, Location, Directory

CosignPort

Syntax: CosignService integer
Default: 6663
Server configuration context: VirtualHost, Location, Directory

CosignService

The name of the Cosign service cookie.

Syntax: CosignService service-name
Default: None
Server configuration context: VirtualHost, Location, Directory

CosignRedirect

The URL of the Cosign login CGI.

Syntax: CosignRedirect URL
Default: None
Server configuration context: VirtualHost, Location, Directory

CosignPostErrorRedirect

The URL to which a user is redirected to if an error is encountered during a POST to the login CGI. This screen informs the user that their data has been dropped.

Syntax: CosignPostErrorRedirect URL
Default: None
Server configuration context: VirtualHost, Location, Directory

CosignRequireFactor

A list of the factors that must be satisfied by the user.

Syntax: CosignRequireFactor Factor1[Factor2...FactorN]
Default: None
Server configuration context: VirtualHost, Location, Directory

CosignFactorSuffix

An optional factor suffix to be used when testing for compliance.

Syntax: CosignFactorSuffix FactorSuffix
Default: None
Server configuration context: VirtualHost, Location, Directory

CosignFactorSuffixIgnore

Toggle whether the value of CosignFactorSuffix is ignored.

Syntax: CosignFactorSuffixIgnore On|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

CosignFilterDB

The path to the Cosign filter database.

Syntax: CosignFilterDB Path
Default: /var/cosign/filter
Server configuration context: VirtualHost

CosignProxyDB

The path to the Cosign proxy database.

Syntax: CosignProxyDB Path
Default: /var/cosign/proxy
Server configuration context: VirtualHost

CosignFilterHashLength

The subdirectory hash length for the Cosign filter database.

Syntax: CosignFilterHashLength 0|1|2
Default: 0
Server configuration context: VirtualHost

CosignTicketPrefix

The path to the Kerberos ticket store.

Syntax: CosignTicketPrefix Path
Default: /ticket
Server configuration context: VirtualHost

CosignProtected

Syntax: CosignProtected On|Off
Default: On
Server configuration context: VirtualHost, Location, Directory, .htaccess

CosignSiteEntry

The URL to which the user is redirected after login.

Syntax: CosignSiteEntry URL
Default: None
Server configuration context: VirtualHost, Location, Directory

CosignAllowPublicAccess

Toggles whether authentication is optional for protected sites.

Syntax: CosignAllowPublicAccess On|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

CosignHttpOnly

Toggles whether the module can be used without SSL. Enabling this directive is not recommended.

Syntax: CosignHttpOnly On|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

CosignCrypto

Paths to the SSL key file, certificate file, and CA directory.

Syntax: CosignCrypto <key file> <cert file> <ca directory>
Default: /var/cosign/certs/key.pem /var/cosign/certs/cert.pem /var/cosign/certs/CA
Server configuration context: VirtualHost, Location, Directory

CosignCookieExpireTime

Syntax: CosignCookieExpireTime time-in-seconds
Default: 86400 (24 hours)
Server configuration context: VirtualHost

CosignGetProxyCookies

Toggles whether module proxy cookies will be requested from cosignd.

Syntax: CosignGetProxyCookies On|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

CosignGetProxyKerberosTickets

Toggles whether the value of "tgt" will be requested from cosignd.

Syntax: CosignGetKerberosTickets On|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

CosignGetProxyKerberosSetupGSS

Toggles whether the enviornment will be set up such that other Apache modules that require GSSAPI or Kerberos will work, such as IMP running under mod_php.

Syntax: CosignGetKerberosSetupGSSOn|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

CosignCheckIP

Toggles whether the browser's IP is verified against cosignd's IP information.

Syntax: CosignCheckIP never|initial|always
Default: initial
Server configuration context: VirtualHost

Note: The certificate CN of the weblogin server must match the value of CosignHostname.

Configuration Example (University of Michigan specific)

In the U of M environment, configure your Apache Virtual Host directives to include the following:

On the http side (port 80), and any dirs or locations that you want to exempt from Cosign protection:

    CosignProtected Off

On port 443 or other https ports, Virtual Host directives should include:

    CosignProtected		On
    CosignHostname		weblogin.umich.edu
    CosignRedirect		https://weblogin.umich.edu/
    CosignPostErrorRedirect https://weblogin.umich.edu/post_error.html
    CosignService		[e-mail to cosign@umich.edu and we will assign]
    CosignCrypto		/path/to/key /path/to/cert /path/to/CAdir

Note: A trailing slash (/) is required on CosignRedirect! The redirects won't work correctly without it.

Restart Apache:

apachectl graceful

For a cron job that prunes old cookies from the filter's database, and for scripts for local logout, see the Cosign support scripts README.

--John DeStefano 11:38, 16 November 2006 (EST)

@@ Line 69: / Line 69: @@
 ==Configuring Apache==
-'''This example is specific to the University of Michigan.'''
+===Apache Configuration Options===
+<tt>mod_cosign</tt> recognizes the following Apache configuration directives:
+====CosignHostname====
+The name of the host running <tt>cosignd</tt>.
+;Syntax: <tt>CosignHostname ''fully-qualified-domain-name''</tt>
+;Default: <tt>cosign.example.edu</tt>
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignPort====
+;Syntax: <tt>CosignService ''integer''</tt>
+;Default: <tt>6663</tt>
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignService====
+The name of the Cosign service cookie.
+;Syntax: <tt>CosignService ''service-name''</tt>
+;Default: None
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignRedirect====
+The URL of the Cosign login CGI.
+;Syntax: <tt>CosignRedirect ''URL''</tt>
+;Default: None
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignPostErrorRedirect====
+The URL to which a user is redirected to if an error is encountered during a '''POST''' to the login CGI. This screen informs the user that their data has been dropped.
+;Syntax: <tt>CosignPostErrorRedirect ''URL''</tt>
+;Default: None
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignRequireFactor====
+A list of the factors that must be satisfied by the user.
+;Syntax: <tt>CosignRequireFactor ''Factor1[Factor2...FactorN]''</tt>
+;Default: None
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignFactorSuffix====
+An optional factor suffix to be used when testing for compliance.
+;Syntax: <tt>CosignFactorSuffix ''FactorSuffix''</tt>
+;Default: None
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignFactorSuffixIgnore====
+Toggle whether the value of <tt>CosignFactorSuffix</tt> is ignored.
+;Syntax: <tt>CosignFactorSuffixIgnore ''On|Off''</tt>
+;Default: <tt>Off</tt>
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignFilterDB====
+The path to the Cosign filter database.
+;Syntax: <tt>CosignFilterDB ''Path''</tt>
+;Default: <tt>/var/cosign/filter</tt>
+;Server configuration context: <tt>VirtualHost</tt>
+====CosignProxyDB====
+The path to the Cosign proxy database.
+;Syntax: <tt>CosignProxyDB ''Path''</tt>
+;Default: <tt>/var/cosign/proxy</tt>
+;Server configuration context: <tt>VirtualHost</tt>
+====CosignFilterHashLength====
+The subdirectory hash length for the Cosign filter database.
+;Syntax: <tt>CosignFilterHashLength ''0|1|2''</tt>
+;Default: <tt>0</tt>
+;Server configuration context: <tt>VirtualHost</tt>
+====CosignTicketPrefix====
+The path to the Kerberos ticket store.
+;Syntax: <tt>CosignTicketPrefix ''Path''</tt>
+;Default: <tt>/ticket</tt>
+;Server configuration context: <tt>VirtualHost</tt>
+====CosignProtected====
+;Syntax: <tt>CosignProtected ''On|Off''</tt>
+;Default: <tt>On</tt>
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>, .htaccess
+====CosignSiteEntry====
+The URL to which the user is redirected after login.
+;Syntax: <tt>CosignSiteEntry ''URL''</tt>
+;Default: None
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignAllowPublicAccess====
+Toggles whether authentication is optional for protected sites.
+;Syntax: <tt>CosignAllowPublicAccess ''On|Off''</tt>
+;Default: <tt>Off</tt>
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignHttpOnly====
+Toggles whether the module can be used without SSL. Enabling this directive is not recommended.
+;Syntax: <tt>CosignHttpOnly ''On|Off''</tt>
+;Default: <tt>Off</tt>
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignCrypto====
+Paths to the SSL key file, certificate file, and CA directory.
+;Syntax: <tt>CosignCrypto ''<key file> <cert file> <ca directory>''</tt>
+;Default: <tt>/var/cosign/certs/key.pem /var/cosign/certs/cert.pem /var/cosign/certs/CA</tt>
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignCookieExpireTime====
+;Syntax: <tt>CosignCookieExpireTime ''time-in-seconds''</tt>
+;Default: <tt>86400</tt> (24 hours)
+;Server configuration context: <tt>VirtualHost</tt>
+====CosignGetProxyCookies====
+Toggles whether module proxy cookies will be requested from <tt>cosignd</tt>.
+;Syntax: <tt>CosignGetProxyCookies ''On|Off''</tt>
+;Default: <tt>Off</tt>
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignGetProxyKerberosTickets====
+Toggles whether the value of <tt>"tgt"</tt> will be requested from <tt>cosignd</tt>.
+;Syntax: <tt>CosignGetKerberosTickets ''On|Off''</tt>
+;Default: <tt>Off</tt>
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignGetProxyKerberosSetupGSS====
+Toggles whether the enviornment will be set up such that other Apache modules that require GSSAPI or Kerberos will work, such as IMP running under <tt>mod_php</tt>.
+;Syntax: <tt>CosignGetKerberosSetupGSS''On|Off''</tt>
+;Default: <tt>Off</tt>
+;Server configuration context: <tt>VirtualHost, Location, Directory</tt>
+====CosignCheckIP====
+Toggles whether the browser's IP is verified against <tt>cosignd</tt>'s IP information.
+;Syntax: <tt>CosignCheckIP ''never|initial|always''</tt>
+;Default: <tt>initial</tt>
+;Server configuration context: <tt>VirtualHost</tt>
+'''Note:''' The certificate CN of the weblogin server must match the value of <tt>CosignHostname</tt>.
+===Configuration Example (University of Michigan specific)===
 In the U of M environment, configure your Apache Virtual Host directives to include the following:
@@ Line 88: / Line 201: @@
 <pre>apachectl graceful</pre>
-See [[Cosign_Wiki:README.scripts.txt|the Cosign support scripts README]] for a cron job that prunes old cookies from the filter's database, and for scripts for local logout.
+For a cron job that prunes old cookies from the filter's database, and for scripts for local logout, see [[Cosign_Wiki:README.scripts.txt|the Cosign support scripts README]].
-===Apache Configuration Options===
-<pre>CosignProtected         [ on | off ]
-            governs whether Cosign is invoked or not
-        CosignHostname          [ the name of the host running cosignd ]
-        CosignRedirect          [ the URL of the cosign login cgi ]
-        CosignPostErrorRedirect [ the URL to redirect to if the user
-                                would be redirected to the login cgi
-                                during a POST. This screen lets people
-                                know we dropped their data. ]
-        CosignService           [ the name of the cosign service cookie ]
-        CosignSiteEntry         [ the URL to redirect to after login  ]
-        CosignCrypto            [path to key] [path to cert] [path to CA dir]
-        CosignRequireFactor     [ a list of the factors a user must satisfy ]
-        CosignFactorSuffix      [ optional factor suffix when testing
-                                for compliance ]
-        CosignFactorSuffixIgnore         [ on | off ]
-        CosignHttpOnly          [ on | off ]
-                module can be use without SSL - not recommended!
-        CosignTicketPrefix      [ the path to the Kerberos ticket store ]
-        CosignFilterDB          [ the path to the cosign filter DB]
-        CosignFilterHashLength  [ 0 | 1 | 2 ]
-            subdir hash for cosign filter DB
-	CosignCheckIP		[ never | initial | always ]
-	    check browser's IP against cosignd's ip information
-        CosignProxyDB           [ the path to the cosign proxy DB]
-        CosignAllowPublicAccess         [ on | off ]
-            make authentication optional for protected sites
-        CosignGetKerberosTickets        [ on | off ]
-            module asks for tgt from cosignd
-        CosignKerberosSetupGSS          [ on | off ]
-            setup the enviornment so that other apache modules
-            that need GSSAPI/Kerberos work. e.g. IMP running under
-	    mod_php
-        CosignGetProxyCookies   [ on | off ]
-            module asks for proxy cookies from cosignd</pre>
-The certificate CN of the weblogin server must match the value of <tt>CosignHostname</tt>.
---[[User:Jd@bnl.gov|John DeStefano]] 16:41, 15 November 2006 (EST)
+--[[User:Jd@bnl.gov|John DeStefano]] 11:38, 16 November 2006 (EST)

cosign wiki:CosignInstallation