cosign wiki:CosignInstallation
From cosign wiki
(→Building and Installing the Filter) |
m (→Configuration Example) |
||
| Line 240: | Line 240: | ||
# handler for a special URI, usually /cosign/valid, where validation of the service URL | # handler for a special URI, usually /cosign/valid, where validation of the service URL | ||
# and the service cookie takes place before granting the user access to the service. | # and the service cookie takes place before granting the user access to the service. | ||
| + | # | ||
| + | # Note: this Location syntax will fail with a 404 if Options Multiviews is set | ||
| + | # in the Directory entry | ||
<Location /cosign/valid> | <Location /cosign/valid> | ||
SetHandler cosign | SetHandler cosign | ||
Current revision
[edit] Building and Installing the Cosign Apache Filter
[edit] 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 wneed 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)
- GNU libtool
[edit] 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
[edit] Building for Red Hat 9 or RHAS 3
required packages:
- httpd-devel
- openssl
- openssl-devel
- libtool
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
[edit] 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
RedHat Enterprise Linux 5 requires different flags. The appropriate flags for your system can be found by using apr-1-config:
/usr/bin/apr-1-config --cppflags
/usr/bin/apr-1-config --cflags
Use the values returned for CFLAGS and CPPFLAGS when running configure.
[edit] 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
Download the latest umwebCA.pem file (http://www.umich.edu/~umweb/umwebCA.pem). cd to the directory containing the downloaded umwebCA.pem file and copy the CA to you CA dir:
cp umwebCA.pem /usr/local/etc/apache/certs/umwebCA.pem
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.0entrust.pem => ed524cf5.0
[edit] Mac OS X
Building and Installing on Mac OS X
Here's some Mac OS X Installation Notes
Notes from a Leopard Server Install
[edit] Configuring Apache
[edit] Apache Configuration Options
mod_cosign recognizes the following Apache configuration directives:
[edit] CosignHostname
The name of the host running cosignd.
- Syntax
- CosignHostname fully-qualified-domain-name
- Default
- cosign.example.edu
- Server configuration context
- VirtualHost, Location, Directory
[edit] CosignPort
The port on which Cosign listens for authentication requests.
- Syntax
- CosignService integer
- Default
- 6663
- Server configuration context
- VirtualHost, Location, Directory
[edit] CosignService
The name of the Cosign service cookie.
- Syntax
- CosignService service-name
- Default
- None
- Server configuration context
- VirtualHost, Location, Directory
[edit] CosignRedirect
The URL of the Cosign login CGI.
- Syntax
- CosignRedirect URL
- Default
- None
- Server configuration context
- VirtualHost, Location, Directory
[edit] 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
[edit] CosignValidReference
A regular expression matching valid service URLs. The administrator uses this directive to ensure users will be redirected to a safe URL following cookie validation.
- Syntax
- CosignValidReference regex
- Default
- None
- Server configuration context
- VirtualHost, Location
- Availability
- Cosign 3.0+
[edit] CosignValidationErrorRedirect
The URL to which a user is redirected if the service URL does not match the regular expression from CosignValidReference, or if mod_cosign cannot validate the service cookie passed from the CGI.
- Syntax
- CosignValidationErrorRedirect URL
- Default
- None
- Server configuration context
- VirtualHost, Location
- Availability
- Cosign 3.0+
[edit] 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
[edit] CosignFactorSuffix
An optional factor suffix to be used when testing for compliance.
- Syntax
- CosignFactorSuffix FactorSuffix
- Default
- None
- Server configuration context
- VirtualHost, Location, Directory
[edit] CosignFactorSuffixIgnore
Toggle whether the value of CosignFactorSuffix is ignored.
- Syntax
- CosignFactorSuffixIgnore On|Off
- Default
- Off
- Server configuration context
- VirtualHost, Location, Directory
[edit] CosignFilterDB
The path to the Cosign filter database.
- Syntax
- CosignFilterDB Path
- Default
- /var/cosign/filter
- Server configuration context
- VirtualHost
[edit] CosignProxyDB
The path to the Cosign proxy database.
- Syntax
- CosignProxyDB Path
- Default
- /var/cosign/proxy
- Server configuration context
- VirtualHost
[edit] CosignFilterHashLength
The subdirectory hash length for the Cosign filter database.
- Syntax
- CosignFilterHashLength 0|1|2
- Default
- 0
- Server configuration context
- VirtualHost
[edit] CosignTicketPrefix
The path to the Kerberos ticket store.
- Syntax
- CosignTicketPrefix Path
- Default
- /ticket
- Server configuration context
- VirtualHost
[edit] CosignProtected
Toggles whether Cosign will protect the directory or location.
- Syntax
- CosignProtected On|Off
- Default
- On
- Server configuration context
- VirtualHost, Location, Directory, .htaccess
[edit] CosignSiteEntry
The URL to which the user is redirected after login.
- Syntax
- CosignSiteEntry URL
- Default
- None
- Server configuration context
- VirtualHost, Location, Directory
[edit] CosignAllowPublicAccess
Toggles whether authentication is optional for protected sites.
- Syntax
- CosignAllowPublicAccess On|Off
- Default
- Off
- Server configuration context
- VirtualHost, Location, Directory
[edit] 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
[edit] 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
[edit] CosignCookieExpireTime
Assigns the expiration time, in seconds, for authentication cookies.
- Syntax
- CosignCookieExpireTime time-in-seconds
- Default
- 86400 (24 hours)
- Server configuration context
- VirtualHost
[edit] CosignGetProxyCookies
Toggles whether module proxy cookies will be requested from cosignd.
- Syntax
- CosignGetProxyCookies On|Off
- Default
- Off
- Server configuration context
- VirtualHost, Location, Directory
[edit] CosignGetProxyKerberosTickets
Toggles whether the value of "tgt" will be requested from cosignd.
- Syntax
- CosignGetKerberosTickets On|Off
- Default
- Off
- Server configuration context
- VirtualHost, Location, Directory
[edit] 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
[edit] 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.
[edit] Configuration Example
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.example.com
CosignRedirect https://weblogin.example.com/
CosignPostErrorRedirect https://weblogin.example.com/post_error.html
CosignService [contact the group that runs your institution's weblogin server to get one assigned]
CosignCrypto /path/to/file.key /path/to/file.cert /path/to/CAdir
# Cosign 3.0+
CosignValidReference https://secure-service\.example\.edu/.*
# Cosign 3.0+ additionally requires the administrator to designate mod_cosign as the
# handler for a special URI, usually /cosign/valid, where validation of the service URL
# and the service cookie takes place before granting the user access to the service.
#
# Note: this Location syntax will fail with a 404 if Options Multiviews is set
# in the Directory entry
<Location /cosign/valid>
SetHandler cosign
CosignProtected Off
Allow from all
Satisfy any
</Location>
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.
Institution-specific information:
--John DeStefano 11:38, 16 November 2006 (EST)
