This page has instructions for building, installing, and configuring CoSign with Apache. These instructions were originally written for Apache 2.x.x on the 32 bit version of Debian/GNU Linux 4.0 (Etch), though more variations are now covered. In any case, they can be used as a guide for your distribution of choice, however some paths and application versions may differ.
- Configure and test website
- Before installing CoSign, be sure to setup your website in Apache's configuration files and verify that the website is reachable from a web browser.
- Configure and test SSL access
- All applications in your service which will be configured to use CoSign must be SSL-protected. Configure and verify the correct behavior of SSL access to your website before you begin the CoSign installation process.
- Register service in WebLogin Management Application (WMC)
- Follow the provided instructions to register your service for CoSign authentication.
- All installations will be required to make TCP connections to weblogin.pennkey.upenn.edu port 6663.
OS Package Prerequisites
If you are using a vendor-packaged Apache (ie., one that ships with your operating system, or is installable using package management tools), you may need to install additionally packages in order to compile CoSign. Use the list appropriate for your operating system.
- RedHat Enterprise Linux & Fedora (install using yum/up2date)
- Debian GNU/Linux & Ubuntu (install using apt)
- apache2-prefork-dev or apache2-threaded-dev
On registration of the service, the WMC determines a unique name for your download package. The full service name looks like this: [domain]-[specified string]-[issuance integer] and is generated from the data entered by you. For example, if the domain selected was net.isc, the specified string was test2, and the issuance integer was 0, then the complete service name for your service that WMC would use would be:
net.isc-test2-0The unique complete service name is used in the key and cert files as well as the download package.
Download the configuration bundle from the WMC. Upload this package to an empty directory on the server on which you've configured and tested the website, as noted above.
Unpack the bundle
- Unzip the bundle.
unzip [domain]-[specified string]-[issuance integer]-Apache2.zip
It contains the following files:
Apache2/cosign3-090824-2.tgz - the Cosign Apache filter source code for Cosign 3 ca-cert.pem - SSL CA used to sign certificates used for CoSign backchannel communication [domain]-[specified string]-[issuance integer].crt - SSL certificate used for CoSign backchannel communication [domain]-[specified string]-[issuance integer].key - SSL key corresponding to aformentioned certificate
- Unpack the CoSign module source code.
tar xzvf Apache2/cosign3-090824-2.tgz
Build the CoSign module
- Change to the source code directory:
cd cosign3-090824-2 OR cd cosign-2.1.1
- Configure the build:
Debian: ./configure --enable-apache2=/usr/bin/apxs2
Red Hat/CentOS 5: ./configure --enable-apache2=/usr/sbin/apxs
Alternative Apache2 prefix: # Example: Apache2 installed in /opt/app/apache2. ./configure --enable-apache2=/opt/app/apache2/sbin/apxs
- Install the module:
sudo make install
There may be some warnings or errors in the make and install processes. As long as the CoSign module for Apache is build and put into place, this is not a problem.
- Create a working directory for CoSign:
mkdir -p /var/cache/cosign/filter
- Give the new directory the proper permissions:
Debian: chown www-data:www-data /var/cache/cosign/filter Red Hat/CentOS 5: chown apache:apache /var/cache/cosign/filter
Apache server configuration
Setup the CoSign certs and key
These steps must be run with root privileges and assume you are in the directory where the cosign zipfile was unpacked.
- Create new directories for the CoSign certs and key
Debian: mkdir /etc/apache2/cosign-ca/ mkdir /etc/apache2/ssl/ Red Hat/CentOS 5: mkdir /etc/httpd/cosign-ca/ mkdir /etc/httpd/ssl/
- Install the certs and keys
Debian: mv ca-cert.pem /etc/apache2/cosign-ca/ c_rehash /etc/apache2/cosign-ca/ mv *.crt *.key /etc/apache2/ssl/ Red Hat/CentOS 5: mv ca-cert.pem /etc/httpd/cosign-ca/ c_rehash /etc/httpd/cosign-ca/ mv *.crt *.key /etc/httpd/ssl/
- Make a filename of the hash of the certificate
NOTE: On RHEL, c_rehash is part of the package openssl-perl. If you don't have it, install it.
If you don't have the c_rehash command installed on your host you can run the following command (requires openssl binary) to achieve the same result:
cd /etc/httpd/cosign-ca/ ln -s ca-cert.pem `openssl x509 -hash -noout -in ca-cert.pem`.0
- Set the permissions on the CA cert
Debian: chmod 644 /etc/apache2/cosign-ca/ca-cert.pem
Red Hat/CentOS 5: chmod 644 /etc/httpd/cosign-ca/ca-cert.pem
- Set the permissions on the service certificate and key
Debian: chown www-data:www-data /etc/apache2/cosign-ca/* chmod 660 /etc/apache2/cosign-ca/*
Red Hat/CentOS 5: chown apache:apache /etc/httpd/ssl/* chmod 660 /etc/httpd/ssl/*
Load the CoSign module
Apache needs to be told to load the CoSign module and the module needs several configuration items including what server to use. Choose either Debian or Non-Debian style configuration options.
- Create a module load file: /etc/apache2/mods-available/cosign.load with the following contents:
LoadModule cosign_module /usr/lib/apache2/modules/mod_cosign.so
- Enable the module
Ensure that Apache restarts successfully before continuing.
- Verify that the following line exists in /etc/httpd/httpd.conf; if it does not, insert it, then restart Apache:
LoadModule cosign_module /usr/lib/httpd/modules/mod_cosign.so
If Apache refuses to load the cosign module, there may be an SELinux problem. The default configuration of a RHEL 5 install has SELinux enabled.
Configure the CoSign module
The following directives can be added to your <VirtualHost> statement. These do not activate CoSign protection on their own but make it possible for <Location>, <Directory> statements and .htaccess files to activate CoSign. Please see the full list of mod_cosign directives.
CosignProtected off CosignHostname weblogin.pennkey.upenn.edu CosignCheckIP never CosignService [service name] CosignRedirect https://weblogin.pennkey.upenn.edu/login CosignPostErrorRedirect https://weblogin.pennkey.upenn.edu/post_error.html CosignFilterDB /var/cache/cosign/filter CosignCrypto /etc/apache2/ssl/[service name].key /etc/apache2/ssl/[service name].crt /etc/apache2/cosign-ca/ CosignValidReference https://[your_server_name]\.upenn\.edu/.* CosignValidationErrorRedirect http://weblogin.pennkey.upenn.edu/validation_error.html
Cosign 3 requires these additional configuration parameters (CosignValidReference, CosignValidationErrorRedirect) for lines in the <VirtualHost> context. Adding these sets up your virtual Validation Handler URL as specified in your service registration. Only add them if you are running Cosign 3, as Cosign 3 uses this location to validate the service cookie and service URL:
<Location /cosign/valid> SetHandler cosign CosignProtected off Allow from all Satisfy any </Location>
NOTE: [service name] needs to be replaced with the name assigned when you registered your app in WMC. More information about Apache mod_cosign directives is available.Although the WebLogin Management Console allows you to specify any validation URL, unless you hve a specific reason for using something else we recommend using:
https://[your_server_name].upenn.edu/cosign/validAlways make sure the URI of the validation URL in the WebLogin Management Console matches the Location value in your validation handler.
NOTE: If you are running Cosign 3, be careful not to override the <Location /cosign/valid> settings with another Location context. Setting "CosignProtected on" in <Location /> or <Location /cosign> will prevent the Cosign module from validating and setting the service cookie correctly. If you need to Cosign-protect the document root, use <Directory /path/to/your/web/server/doc/root> instead of <Location />.
These CoSign directives need to be loaded before any other CoSign directives. Where to put these lines depends on your distribution and your configuration preferences.
- Disable the module
- Put the above statements into the file: /etc/apache2/mods-available/cosign.conf
- Enable the module
- Restart Apache
This will cause these statements to be loaded when the module is loaded (before the site configurations).
An alternate place to put these configuration directives is in the main section of the /etc/apache2/sites-available/default-ssl file.
Add the above statements to the main section of the apache configuration file or the main section of the HTTPS virtual host configuration file.
Protect websites with CoSign
To protect a directory, put the following statements in a .htaccess file in that directory.
CosignProtected On AuthType Cosign Require valid-user CosignRequireFactor UPENN.EDU
To protect an individual file, put the following in a .htaccess file in the same directory or a higher-level directory.
<Files "file name.html"> CosignProtected On AuthType Cosign Require valid-user CosignRequireFactor UPENN.EDU </Files>
Cron cleanup of CosignFilterDB directory
The Apache Cosign filter creates a file named cosign-<cosign service>=<user cookie value> on the file system under the CosignFilterDB location for each user-initiated session. These files contain the REMOTE_ADDR, REMOTE_USER, REMOTE_REALM and COSIGN_FACTOR environment variables for the session. They are not automatically purged once they expire so a process needs to be put in place to periodically delete the old session files so they don't endlessly accumulate. Add a job under the apache user's crontab that runs at some interval and cleans up files of a certain age in the CosignFilterDB directory. Below is an example of job that runs nightly and removes anything older than 24 hours (Cosign's default cookie expiration time):
13 0 * * * find /var/cache/cosign/filter -type f -mtime +1 | xargs rm -f