9.3. Setup Single-Sign-ON with CAS

Starting with version 0.4.4 (revision 4), the AuditConsole provides additional support for centralized authentication using CAS (Central Authentication Service). CAS is a ticket-based authentication scheme that relies on a central authentication server.

The CAS authentication has been tested with the JASIG CAS server, a free and open-source CAS server implementation available at www.jasig.org.

9.3.1. How CAS works

The CAS service is a ticket-based authentication token. Once accessing the CAS-enabled AuditConsole, the user will be forwarded to a CAS login server. There the user has to authenticate using her credentials (username,password) which will create an authenticated ticket for the authenticated user.

The following figure outlines the authentication phase of the CAS authentication process:

With that ticket, the user is redirected back to the AuditConsole, which checks validity of the ticket and logs in the user with that ticket. To do this, the AuditConsole looks up the user by the username associated with the ticket in its local user database.

The following figure shows the ticket validation process. Given, that the user already authenticated against CAS, the AuditConsole needs to validate the granted ticket by asking the CAS for validation.

It is important to note that for ticket validation (steps 4 and 5 in the figure above), there needs to be a secure connection between the AuditConsole and the CAS server.

9.3.2. Preparing the CAS Setup

The CAS authentication relies on a secure communication channel between the CAS server and the CAS client (the AuditConsole). This is established using an encrypted HTTPS connection.

In order for the AuditConsole to successfully connect to the CAS server, the CAS server's certificate used for HTTPS needs to be known to the AuditConsole, i.e. the Java environment that is running the AuditConsole.

Installing the CAS Server Certificate

In this section I will assume that the variable $JAVA_HOME points to the Java home directory of the JVM you ar running the AuditConsole with. Usually this directory is located in /usr/java/jdk1.6.0_17 or similar on Unix/Linux machines.

The $JAVA_HOME directory provides a sub directory structure containing jre/lib/security/ which in turn contains the cacerts file. This file is a Java Keystore that provides the list of trusted certificates of your Java environment.

Assuming you have your CAS server certificate in cas.cert the following command will allow you to import that certificate into your Java cert-store:

# sudo keytool -importcert -file cas.cert -keystore $JAVA_HOME/jre/lib/security/cacerts

As the cacerts file is usually only write-accessible to the super-user you will need to switch to root or use sudo.

Importing Certificates on Mac OS

On Mac OS systems the Java home is usually found in /Library/Java/Home. The location of the cacerts file differs a bit as well (note the absence of jre):

/Library/Java/Home/lib/security/cacerts

Therefore the following command is to be used on Mac OS systems:

# sudo keytool -importcert -file cas.cert -keystore /Library/Java/Home/lib/security/cacerts

9.3.3. Setting up the AuditConsole with CAS

The AuditConsole web directory contains the setup of the authentication mechanism and already comes with a prepared configuration for enabling CAS authentication. In the following we will refer to the AuditConsole web-root by $CONSOLE_WEB.

If you are running the RPM/Debian or standalone version, then the $CONSOLE_WEB directory is located at /opt/AuditConsole/lib/console.

When using the WAR archive, then the $CONSOLE_WEB is the web-application directory where you unpacked the WAR file.

The following figure shows the basic layout of the AuditConsole web directory with the files we need to change for CAS authentication:

The steps for setting up CAS within the AuditConsole are:

  1. Replace default-authentication.xml with cas-authentication.xml
  2. Adjust cas.properties to match your CAS server settings
  3. Restart the AuditConsole

1. Replacing default-authentication.xml

The AuditConsole web application provides a sample file for CAS authentication. It is called cas-authentication.xml and resides in the WEB-INF directory. This file provides all settings to plug CAS authentication into the spring-framework, that is empowering the AuditConsole.

To use CAS authentication you need to replace the file default-authentication.xml in WEB-INF/config/ with cas-authentication. These files cannot co-exists in that folder in parallel.

2. Adjusting your cas.properties

The next step towards CAS authentication is to set up your CAS properties. These are defined in the file WEB-INF/cas.properties and need to contain your CAS server URL as well as the public address of your AuditConsole server.

The following example cas.properties shows the settings for authenticating the AuditConsole at http://console.jwall.org against the CAS server running at https://auth.jwall.org:

# the CAS authentication server
#
cas.server.url=https://auth.jwall.org/cas

# the AuditConsole service URL
#
console.server.url=http://console.jwall.org

3. Restarting the AuditConsole

After restarting the AuditConsole, accessing the AuditConsole web interface should redirect your browser to the CAS login.