cosign wiki:CosignInstallation
From cosign wiki
Contents |
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
This example is specific to the University of Michigan.
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
See the Cosign support scripts README for a cron job that prunes old cookies from the filter's database, and for scripts for local logout.
Apache Configuration Options
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
The certificate CN of the weblogin server must match the value of CosignHostname.
--John DeStefano 16:41, 15 November 2006 (EST)
