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.

Prerequisites

1. 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.
2. 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.
3. Register service in WebLogin Management Application (WMC)
   • Follow the provided instructions to register your service for CoSign authentication.

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)
  • httpd
  • httpd-devel
  • mod_ssl
  • openssl-devel
  • openssl-perl
• Debian GNU/Linux & Ubuntu (install using apt)
  • build-essential
  • unzip
  • apache2
  • apache2-prefork-dev or apache2-threaded-dev
  • apache2-utils
  • apache2.2-common
  • libssl-dev
  • libssl0.9.8
  • openssl

WMC Registration

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-0

The 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
  

• Build:

   make
  

• 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.

Post-install

• 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.

Debian style

• 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

  a2enmod cosign

• Restart Apache

  /etc/init.d/apache2 restart

Ensure that Apache restarts successfully before continuing.

Non-Debian style

• 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
  

Ensure that Apache restarts successfully before continuing.
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/valid

Always 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.

Debian style

• Disable the module

  a2dismod cosign

• Put the above statements into the file: /etc/apache2/mods-available/cosign.conf
• Enable the module

  a2enmod cosign

• Restart Apache

  /etc/init.d/apache2 restart

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.

Non-Debian style

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

External links

• CoSign Home
• Apache ReadMe.txt
• Comprehensive CoSign Scheme
• Info about 64-bit build problem (incomplete).
• CoSign install on Debian doc from Penn State