Installing and configuring CoSign on a web server

The instructions on this page cover installation and configuration of the CoSign software on an Tomcat web server.

If you want to install CoSign on Apache, the instructions on installing Cosign on Apache might be useful.

If you want to install CoSign on Windows, the instructions on installing Cosign in IIS 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.

What is 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.

How to install JavaCosign on a Tomcat web server

Tomcat implements the Java Servlet specification, so it can use the JavaCosign authentication filter module.

There are a number of stages in setting up a server to use JavaCosign, instructions below assume a starting point of a Fedora Linux system, and a basic understanding of how to administer a unix system.

You will normally need to be logged in as the 'root', or have equivalent rights via the su or sudo command.

If it is not already installed, on Fedora Linux you can install Tomcat and the sample webapps with the following command:

yum install tomcat6 tomcat6-webapps

On Fedora Linux, the install directory for tomcat6 is /usr/share/tomcat6, so all config files will be relative to this. On a different system the install directory may be different, but the procedure should be very similar.

It's assumed that all commands will be relative to the tomcat home directory, e.g. on a Fedora system you should:

cd /usr/share/tomcat6

Create a private key and request a certificate for use with 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).

JavaCosign uses the Java Cryptography Architecture, so creating a key and requesting a certificate is done with keytool

create a keystore
keytool -genkey -keyalg "RSA" -keysize 2048 -keystore conf/jcosign.jks
You'll be prompted for
password (you'll reuse this later) "your first and last name"
- this must be the fully qualified domain name that the server will be accessed by,
- e.g. someserver.lancs.ac.uk "the name of your organizational unit"
- this should be the department or faculty name
- e.g. ISS "the name of your organization"
- e.g. "Lancaster University" "the name of your City or Locality?"
- e.g. "Lancaster" "the name of your State or Province?"
- e.g. "Lancs" "the two-letter country code for this unit?"
- e.g. "GB"
download and import the local CA certificates
wget https://www.lancs.ac.uk/iss/ca/LUrootCA.pem -O conf/LUrootCA.pem wget https://www.lancs.ac.uk/iss/ca/LU-rootca-2016.pem -O conf/LU-rootca-2016.pem wget https://www.lancs.ac.uk/iss/ca/LU-cosignca-2016.pem -O conf/LU-cosignca-2016.pem keytool -keystore conf/jcosign.jks -importcert -alias LUrootCA -file conf/LUrootCA.pem keytool -keystore conf/jcosign.jks -importcert -alias LU-rootca-2016 -file conf/LU-rootca-2016.pem keytool -keystore conf/jcosign.jks -importcert -alias LU-cosignca-2016 -file conf/LU-cosignca-2016.pem
generate a CSR
keytool -certreq -keyalg "RSA" -file conf/csr.pem -keystore conf/jcosign.jks
 get the certificate signed: email the CSR to Steve Bennett. import the received certificate into the keystore
keytool -keystore conf/jcosign.jks -keyalg "RSA" -import -file conf/cert.pem
if you get an error like "lengthTag=127, too big", you might have extraneous lines or characters in the imported certificate
if you get an error "Failed to establish chain from reply", you need to didn't install the local CA certificates

Install and Configure JavaCosign

JavaCosign can be downloaded from http://cosign.sourceforge.net/download.shtml . The current version is v3.0.0. The downloaded file JavaCosignV3.jar should be moved to the tomcat 'lib' directory:
mv JavaCosignV3.jar lib/
 JavaCosign uses the Apache Commons Logging framework, which on Fedora Linux isn't on tomcat's classpath.
The following command links it in:
ln -s /usr/share/java/apache-commons-logging.jar lib/commons-logging.jar
 The following entries should be added to conf/web.xml, before the line '</web-app>':
<filter> <filter-name>Cosign Authentication Filter</filter-name> <filter-class>edu.umich.auth.cosign.CosignAuthenticationFilterIII</filter-class> <init-param> <param-name>Cosign.ConfigurationFile</param-name> <param-value>conf/cosignConfig.xml</param-value> </init-param> <init-param> <param-name>Auth.JAASConfigurationFile</param-name> <param-value>conf/jaas.conf</param-value> </init-param> </filter> <!-- the following entry is required for URL validation --> <!-- it should not be modified --> <filter-mapping> <filter-name>Cosign Authentication Filter</filter-name> <url-pattern>/cosign/valid/*</url-pattern> </filter-mapping> <!-- the following entry is an example of how to enable --> <!-- CoSign authentication on a URL. --> <filter-mapping> <filter-name>Cosign Authentication Filter</filter-name> <url-pattern>/cosign-secure/*</url-pattern> </filter-mapping> <!-- Of course, you can also add <filter-mapping> --> <!-- entries in web.xml in other webapp directories -->
conf/cosignConfig.xml should contain the following:
<?xml version="1.0" encoding="UTF-8"?> <CosignConfig> <!-- where to find the certificates --> <KeyStorePath>conf/jcosign.jks</KeyStorePath> <KeyStorePassword>keystore password</KeyStorePassword> <CosignServerHost>cosign.lancs.ac.uk</CosignServerHost> <CosignServerPort>6663</CosignServerPort> <ConnectionPoolSize>30</ConnectionPoolSize> <LoginRedirectUrl>https://weblogin.lancs.ac.uk/</LoginRedirectUrl> <LoginPostErrorUrl>https://weblogin.lancs.ac.uk/cosign/post_error.html</LoginPostErrorUrl> <LoginSiteEntryUrl> </LoginSiteEntryUrl> <CheckClientIP>false</CheckClientIP> <HttpsOnly>false</HttpsOnly> <HttpsPort>8443</HttpsPort> <ClearSessionOnLogin>true</ClearSessionOnLogin> <ConfigFileMonitoringIntervalSecs>5</ConfigFileMonitoringIntervalSecs> <CosignServerHostIpCheck>2</CosignServerHostIpCheck> <!-- which URL is used for handling URL validation --> <LocationHandlerRef>/cosign/valid/</LocationHandlerRef> <!-- where to redirect users if there's a redirection error --> <ValidationErrorRedirect></ValidationErrorRedirect> <!-- Regex to limit what redirections are considered valid. --> <!-- This is generic, you can make it more restrictive --> <RedirectRegex>https?://.*\.lancs\.ac\.uk(:\d+)?/.*</RedirectRegex> <!-- If you need to vary the service name depending on the --> <!-- requested URL, you can specify the patterns here. --> <!-- However, most servers only need a single service name, --> <!-- so a pattern of '/*' covers everything. --> <services> <service name="cosign-https-webapp.lancs.ac.uk" > <protected>/*</protected> </service> </services> </CosignConfig>
Keystore password
This is the value you used when creating the keystore.
CoSignService
This should have a value of either "cosign-http-hostname" or "cosign-https-hostname", where hostname is the fully qualified DNS name for your service (it must match the Subject CN of the CoSign certificate).
  • You should use "cosign-http-hostname" if your service uses HTTP (CosignHttpOnly is "on").
  • You should use "cosign-https-hostname" if it uses HTTPS (CosignHttpOnly is "off").
For example, the correct value of CosignService for an application hosted at https://webapp.lancaster.ac.uk/ would be "cosign-https-webapp.lancaster.ac.uk"
 The file 'conf/jaas.conf' should contain the following:
CosignAuthentication { edu.umich.auth.cosign.CosignLoginModule required; };
The directory 'cosign/valid' must exist in the ROOT webapp:
mkdir -p webapps/ROOT/cosign/valid

Restart Tomcat and test JavaCosign

Some of the changes above require tomcat to be restarted before they take effect, so now is a good time to restart the service:
service tomcat6 restart
 It's worth checking that JavaCosign is working correctly. Add a small JSP page to a URL that is enabled for CoSign authentication. For example, create a file 'hellocosign.jsp' in the directory 'webapps/ROOT/cosign-secure/':
<html><head> <title>Hello World</title> </head><body> Hello <%= request.getRemoteUser() %> ! </body></html>
When you visit this page (i.e. 'http://hostname/cosign-secure/hellocosign.jsp') you will be redirected to https://weblogin.lancs.ac.uk/ if you need to authenticate, and then you should see something like:
Hello steveb !
Steve Bennett
last updated: 15/02/2016