How to Install the Apache Filter

Requirements

• Apache enabled for dynamic modules.
• OpenSSL 0.9.7d or newer.
• MIT krb5-1.2.7 or newer if you will need Kerberos
credentials. (Most sites should not need credentials.)
• Access to your Apache's apxs command.
• If testing v3, review the information for upgrading to cosign v3.

Downloading

From the CoSign home page, download and extract the "CoSign Source" tar.gz file.

Building

Examine the README for details (including workarounds for Red Hat 9 if using Kerberos).

Short version of steps to create and install the module:

./configure
make
make install # uses apxs to install the module
mkdir -p /var/cosign/filter # this location can be changed via configure or runtime option
chown APACHE_USER /var/cosign/filter # APACHE_USER being the user name your server uses

Penn State web admins have had success with: Apache 1/AIX 5.2, Apache 1/Solaris 9, Apache 1/Mac OS X (with local build), Apache 2/Red Hat 9. Apache 2 sites may need to tweak the configure options.

For Mac OS X 10.2 or later: According to the FAQ at the CoSign home site, they have not been able to create a module that loads with the Apache that Apple distributes. Their work around is build and use your own Apache (or compiling the module on an older version of OS X). Others have found that the filter will build and install under Mac OS X Server.

Certificates

Your Certificate

As mentioned previously, the CoSign filter needs its own certificate and key for the connection to the CoSign servers. However, if you already have a certificate (with its key) from a Certificate Authority, it can be reused for this purpose.

Place a copy of the certificate and key files into the appropriate locations for your filter. Configuration options allow you to place them anywhere, but the default locations work well. For Apache filter, you can just use the copies that Apache has (if the user which Apache runs as, also has access to all of the files).

If you don't have a certificate yet, and would like a one from a Certificate Authority (CA) already configured into common browsers, see our Penn State SSL Certificate Group Purchase Program for buying a low-cost Thawte certificate. If you'd prefer a free certificate, look into the ones available from CAcert.

Certificate Authorities

Your server's filter needs to have a copy of the Certificate Authority (CA) for the CoSign server's certificate, and the CoSign server needs to have a copy of the CA for your certificate. This allows the encrypted connection between them to use mutual authentication.

The CoSign server currently knows these public CAs:

• Thawte Premium Server CA
• Thawte Server CA
• CA Cert Signing Authority
• VeriSign International Server CA - Class 3
• RSA Data Security, Secure Server Certification Authority

If your certificate was signed by another public CA, contact us so that it can be added to the list.

As of May 1, 2006, the CA for our CoSign server is the Thawte Premium Server CA: if you don't have their certificate, you can download a copy from here, and save it with the other CAs that mod_ssl is using (don't forget to rehash the directory!).

Registering your Certificate

Not only does the CoSign server need to know the CA for your certificate, it also needs to know the Common Name (CN) of it. If you're using the web server certificate, that's just the full name of your web site. Give us the CN and contact information (for notification purposes).

Apache Filter Configuration

If you did the make install above, a LoadModule directive was added to your httpd.conf similar to this

LoadModule cosign_module      libexec/mod_cosign.so

You'll also need to add these CoSign specific directives to the httpd.conf file (items highlighted like this need to be customized for your site):

CosignProtected On
CosignHostname webaccess.psu.edu
CosignRedirect https://webaccess.psu.edu/
CosignPostErrorRedirect https://webaccess.psu.edu/post_error.html
CosignService your-service-name-here
CosignCrypto /psuopt/conf/ssl.key/my.key /psuopt/conf/ssl.crt/my.crt /psuopt/conf/ssl.crt

Where

CosignProtected	Turns CoSign protection on for the entire server. You can also set it off here, and use <Directory> or <Location> directives to enable it for specific parts.
CosignHostname	The host name for our cosign back-end service.
CosignRedirect	The URL which provides the login page for us.
CosignPostErrorRedirect	Where the browser should be redirect to, should a login session expire while at a web page with POST form data.
CosignService	Your service name, i.e., the CN on your certificate.
CosignCrypto	Paths to: your certificate's key, your certficate, and your CA directory (resp.).

Activating the Filter

The filter should be loaded and run when the Apache server is started (via, e.g., apachectl startssl).

Daily Maintenance

The apache filter doesn't clean up after itself: you'll need to do that. Look in the scripts/cron directory of the source tree, and you'll find a one-liner cron job like this

# this command will delete cosign files ( filter or daemon ) that are
# older than a day

/usr/bin/find /var/cosign -type f -mtime +1 | /usr/bin/xargs /usr/bin/rm -f

Which you can use on a daily basis (since we don't have login times longer than 24 hours). Don't forget to modify the starting directory to match what you've configured.

Performing Authorization Checks

The filter only provides basic authentication: that an active account has successfully logged into the WebAccess server. Although it makes the account name and realm available to the Apache server, no further checking is performed. However, there are a few different ways to do authorization (authZ):

• Server Side Scripts (CGI's, PHP, etc.) can access the variables directly
• Using Apache's existing Require directive
• Implementing other Apache modules

Server Side Scripts

The account name and realm are available in the environment variables

REMOTE_USER
REMOTE_REALM

and the Access Account's realm is dce.psu.edu.

Apache Require Directive

The filter fits in well with the existing Apache mod_auth* system. In an .htaccess file, you can use something like this

AuthType Cosign
Require user aaa111 zxy999

to restrict access to those two accounts. If you want a little more flexiblity, you can also use any of

AuthUserFile
AuthGroupFile
AuthDBMUserFile
AuthDBMGroupFile

to manage your list of account names along with the appropriate Require user or Require group.

Other Apache Modules

Any Apache module that refers to REMOTE_USER can be used in conjunction with the filter. The developers of CoSign have documented using mod_authz_ldap (with a patch from them), and that's available here.