The instructions on this page cover installation and configuration of the CoSign software on an Apache web server.
If you want to install CoSign on Windows, the instructions on installing CoSign in IIS might be useful.
If you want to install CoSign on a Tomcat web server, the instructions on installing CoSign in Tomcat might be useful.
If you simply want to use CoSign functionality on a server that already has CoSign installed and configured, you should read the instructions on using CoSign.
CoSign is the Web Single Sign-On operated by ISS for use on central and departmental web servers and applications. Where possible, CoSign authenticates users (i.e. proves their identity) based on their existing credentials, so that no additional password prompts are necessary. Where this is not possible, either because there are no existing credentials, or because the browser is unable to pass them securely, the user will be prompted for his or her password just once per browser session, and the password will always be sent over a secure connection.
CoSign Web applications do not need to handle users' passwords; they are simply notified of the user's identity.
CoSign has been tested with a wide variety of browsers and operating systems, and is believed to operate correctly and securely in all circumstances.
mod_cosign is an authentication filter module for Apache httpd that is required for participation in a CoSign Single Sign-On environment.
There are a number of stages in setting up a server to use mod_cosign:
CoSign uses SSL to authenticate and encrypt communication between different components. Each web server in a CoSign environment requires an SSL certificate. This certificate is quite distinct from any certificates that are used to serve SSL-protected HTTP, and needs to be configured to act as an SSL client ('normal' certificates are configured to be an SSL server).
To obtain a suitable certificate, send a CSR to
Steve Bennett.
There are instructions on creating a CSR if you're not familiar with the procedure.
Make sure that the private key does not have a passphrase protecting it, since CoSign has no facility for prompting you for a pasphrase.
Source code for mod_cosign is available from: http://sourceforge.net/projects/cosign/files/cosign/
Here's an example of some settings that work to build mod_cosign version 2.0.1 on a 32 bit x86 Fedora 6 install running Apache httpd version 2.2.3:
BASEDIR=/usr/local/packages/httpd
CPPFLAGS="-D_LARGEFILE64_SOURCE" \
./configure --prefix=${BASEDIR} \
--enable-apache2=${BASEDIR}/bin/apxs \
--enable-krb \
--with-cosignconf=${BASEDIR}/etc/cosign.conf \
--with-cosignhost=cosign.lancs.ac.uk \
--with-cosignlogouturl=https://weblogin.lancs.ac.uk \
--with-cosignloopurl=https://weblogin.lancs.ac.uk/looping.html
make
Other settings are available, but the default values should mostly be OK.
(TODO: Instructions for other platforms)
make installThere are some additional directories that need to be created:
mkdir -p /var/cosign/filter /var/cosign/certs/CA chown www /var/cosign/filter chmod a+r /var/cosign/certs
'www' should be replaced by the username that the httpd process runs as (some installations use 'apache' or 'httpd').
The directory /var/cosign/filter is the location that the filter uses to cache CoSign session credentials. If necessary, the location can be modified by passing --with-filterdb=dir to configure.
CoSign doesn't clear old cookies out from the filterdb path, so you'll need to arrange for this to be done periodically. I generally have a script to do daily webserver tidying, and it has a line like:
# clean up old cosign cookies find /var/cosign/filter -type f -mtime +7 -print0 | xargs -0 rm -fTODO: describe filterhashlen
Copy the private key (generated as part of the certificate signing request) and the certificate itself (returned to you by ISS) into the directory /var/cosign/certs.
Install the CA certificates into the directory /var/cosign/certs/CA:
curl -L https://www.lancs.ac.uk/iss/ca/LUrootCA.pem -o LUrootCA.pem curl -L https://www.lancs.ac.uk/iss/ca/LU-rootca-2016.pem -o LU-rootca-2016.pem curl -L https://www.lancs.ac.uk/iss/ca/LU-cosignca-2016.pem -o LU-cosignca-2016.pem mv LUrootCA.pem LU-rootca-2016.pem LU-cosignca-2016.pem /var/cosign/certs/CA c_rehash /var/cosign/certs/CA
You should see output something like:
Doing /var/cosign/certs/CA/ LUrootCA.pem => 1db45132.0 LU-rootca-2016.pem => 806ff0bd.0 LU-cosignca-2016.pem => 14b397c4.0
If you do not see this output you may have a missing package (on Fedora systems the package 'openssl-perl' must be installed).
You can verify that the certificates are all installed and in the correct places with:
openssl verify -CApath /var/cosign/certs/CA -purpose sslclient \ /var/cosign/certs/cert.pem
Where cert.pem is the filename that you used for the certificate for mod_cosign.
Finally, Apache httpd needs to be configured to use CoSign. Most of the options are part of the global configuration (normally in the file httpd.conf), but some can be modified within directories that have AllowOverride Auth enabled.
CosignHostname cosign.lancs.ac.uk CosignRedirect https://weblogin.lancs.ac.uk/ CosignPostErrorRedirect \ https://weblogin.lancs.ac.uk/cosign/post_error.html CosignCrypto /var/cosign/certs/privkey.pem \ /var/cosign/certs/cert.pem \ /var/cosign/certs/CA CosignService cosign-http-webapp.lancs.ac.uk CosignHttpOnly on CosignProtected Off CosignCheckIP never CosignValidReference ^https?://webapp\.(lancs|lancaster)\.ac\.uk(/.*)? CosignValidationErrorRedirect \ https://weblogin.lancs.ac.uk/cosign/validation_error.html CosignAllowValidationRedirect on <Location /cosign/valid> SetHandler cosign CosignProtected Off Allow from all Satisfy any </Location>
diff --git a/filters/apache2/mod_cosign.c b/filters/apache2/mod_cosign.c
index 2d4e95d..5a919ef 100755
--- a/filters/apache2/mod_cosign.c
+++ b/filters/apache2/mod_cosign.c
@@ -340,7 +340,7 @@ cosign_handler( request_rec *r )
}
cv = cosign_cookie_valid( cfg, cookie, &rekey, &si,
- r->connection->remote_ip, r->server );
+ r->connection->client_ip, r->server );
if ( rekey != NULL ) {
/* we got a rekeyed cookie. let the request pool free it later. */
apr_pool_cleanup_register( r->pool, (void *)rekey, (void *)free,
@@ -528,7 +528,7 @@ cosign_auth( request_rec *r )
* Otherwise, retrieve the auth info from the server.
*/
cv = cosign_cookie_valid( cfg, my_cookie, NULL, &si,
- r->connection->remote_ip, r->server );
+ r->connection->client_ip, r->server );
if ( cv == COSIGN_ERROR ) {
return( HTTP_SERVICE_UNAVAILABLE ); /* it's all forbidden! */
}
Also note since that the permissions model on httpd 2.4.x
is more flexible than in earlier versions,
if you want to restrict access to content you may need an additional directive:
Require valid-user