Introduction

The Web Service Security (WSS) Implementation that comes with DDF was built to be run independent of an SSO or authentication mechanism. Testing out the security functionality of DDF was performed by using the Central Authentication Server (CAS) software. This is a popular SSO appliance and allowed DDF to be tested using realistic use cases. Within this page you will find configurations and settings that we have used to help configure CAS to work within the DDF environment.

General Server Setup and Configuration

The following steps are shown for installing CAS to a Tomcat 7.x server running in Linux. Other configurations, like different versions of Tomcat or other Operating System types, may have slight differences from these steps. Additionally, the setenv.sh file would need to be converted (to a .bat if using Windows).

Installation using DDF CAS WAR

DDF comes with a custom distribution of the CAS web application that comes with LDAP and x509 support configured and built-in. Using this configuration can help save time and setup.

Download and Unzip Tomcat Distribution
```
$ unzip apache-tomcat-7.0.39.zip
```
Setup Keystores and enable SSL. There are sample configurations located within the security-cas-server-webapp project.
1. Copy setenv.sh (ddf-trunk/security/cas/security-cas-server/src/main/resources/tomcat/bin) to TOMCAT/bin
```
$ cp /ddf-trunk/security/cas/security-cas-server/src/main/resources/tomcat/setenv.sh apache-tomcat-7.0.39/bin/
```
  Make sure to convert setenv.sh to a .bat file if Tomcat is being installed on a windows machine.
2. Copy server.xml (ddf-trunk/security/cas/server/security-cas-server-webapp/src/main/resources/tomcat/conf) to TOMCAT/conf
```
$ cp /ddf-trunk/security/cas/security-cas-server/src/main/resources/tomcat/conf/server.xml apache-tomcat-7.0.39/conf/
```
3. By default, the above files point to TOMCAT/certs/keystore.jks as the default keystore location to use. This file does not come with Tomcat and either needs to be created or the files copied above (setenv.sh and server.xml) need to be modified to point to the correct keystore.
```
$ mkdir apache-tomcat-7.0.39/certs
$ cp keystore.jks apache-tomcat-7.0.39/certs/
```
Start Tomcat
```
$ cd apache-tomcat-7.0.39/bin/
$ ./startup.sh
```
Make sure to run startup.bat instead of startup.sh if windows is running on a window machine (also, if you did not convert setenv.sh to a .bat above then startup.bat will not function correctly).

Deploy the DDF CAS WAR to Tomcat

$ cp /ddf-trunk/security/cas/security-cas-server/target/cas.war apache-tomcat-7.0.39/webapps/

CAS should now be running on the tomcat server. To verify it started without issues, check the tomcat log and look lines similar to the following:

Apr 25, 2013 10:55:39 AM org.apache.catalina.startup.HostConfig deployWAR
INFO: Deploying web application archive /apache-tomcat-7.0.39/webapps/cas.war
2013-04-25 10:55:42,831 INFO [org.jasig.cas.services.DefaultServicesManagerImpl] - <Loaded 1 services.>
2013-04-25 10:55:43,540 INFO [org.jasig.cas.util.AutowiringSchedulerFactoryBean] - <Starting Quartz Scheduler now>

CAS will try to authenticate first with x509 (using the keystore provided as the truststore) and failover to LDAP username / password.

The DDF distribution of CAS is configured to use the embedded DDF instance running on localhost. Configuring the LDAP location can be done by modifying the bottom of the cas.properties file located in TOMCAT/webapps/cas/WEB-INF/ after the web application is deployed.

Configuring Existing CAS Installation

For upgrading an existing CAS installation or using the standard CAS web application go to the Configuring CAS for LDAP page or the Configuring CAS for X509 User Certificates page for directions on specific configurations that need to be performed.

As part of setting up the server, it is critical to make sure that Tomcat trusts the DDF server certificate and that DDF trusts the certificate from Tomcat. If this is not done correctly, CAS and/or DDF will throw certificate warnings in their logs and will not allow access.

Configuring for DDF

When configuring CAS to integrate with DDF, there are two main configurations that need to be modified. By default, DDF uses 'server' as the hostname for the local DDF instance and 'cas' as the hostname for the CAS server.

CAS Client

The CAS client bundle contains CAS client code that can be used by other bundles when validating and retrieving tickets from CAS. This bundle is extensively used when performing authentication.

When setting up DDF, the 'Server Name' and 'Proxy Callback URL' must be set to the hostname of the local DDF instance.

The 'CAS Server URL' configuration should point to the hostname of the CAS server and should match the SSL certificate that it is using.

CAS Token Validator

The 'CAS Server URL' configuration should point to the hostname of the CAS server and should match the SSL certificate that it is using.

Additional Configuration

Information on each of the CAS-specific bundles that come with DDF as well as their configurations can be found on the Security CAS application page.

Example Workflow

A sample workflow showing how CAS integrates within the DDF WSS Implementation is described below:

User points browser to DDF Query Page.
CAS servlet filters are invoked during request
(Assuming user is not already signed in) User is redirected to CAS login page.
1. For x509 authentication, CAS will try to obtain a certificate from the browser. Most browsers will prompt the user to select a valid certificate to use.
2. For username / password authentication, CAS with display a login page.
After successful sign-in, user is redirected back to DDF Query page.
DDF Query Page obtains the Service Ticket sent from CAS, gets a Proxy Granting Ticket (PGT), and uses that to create a Proxy Ticket for the STS.
User fills in search phrase and hits 'search'
Security API uses the incoming CAS proxy ticket to create a RequestSecurityToken call to the STS.
STS validates the proxy ticket to CAS and creates SAML assertion.
Security API returns a Subject class that contains the SAML assertion.
Query Page creates a new QueryRequest and adds the Subject into the properties map.

From #10 on, the message is completely de-coupled from CAS and will proceed through the framework properly using the SAML assertion that was created in step 8.

External Links

Official CAS Documentation: https://wiki.jasig.org/display/CASUM/Home

Browser not supported