This tutorial demonstrates Active Directory authentication, MySQL-based registries, LDAP attribute release and single sign-off using the 188.8.131.52 server and 3.1.10 client running on Windows XP systems. The Maven overlay method is used to build the server.
This document describes work I did to evaluate CAS. This is intended to be a beginner's introduction. I'm not a member of the CAS team and I don't have a lot of experience with the system, so I imagine there are more efficient ways to go about this - feel free to correct errors or improve the results!
I think the following is a fairly realistic implementation of a CAS SSO environment. I say "fairly" because it doesn't reflect some things that a real production deployment would have, i.e., a high-availability architecture.
The system demonstrates the following features in one of many possible CAS setups:
And it shows how I used the Maven overlay method to build the server.
The CAS system requires a ticket registry to hold the artifacts of the users' login sessions. A service registry is required to hold information on which applications are allowed to use the SSO infrastructure, as well as which user attributes can be released to each application. Both the ticket registry and the service registry are kept in a MySQL database running on the CAS server.
There are two test applications running on a protected web server. Single sign-on can be exercised by following links between the two apps. The test application is described later.
Install the Required Software
This demo uses JDK version 1.6_20. Make sure the JAVA_HOME system environment variable points to the JDK, e.g., C:\Program Files\Java\jdk1.6.0_20. Make sure the java executables directory is in the PATH environment variable, i.e., %JAVA_HOME%\bin.
Maven is a project management application that uses xml files to specify a project's dependencies and the repositories they reside in. Dependencies are downloaded to the local system as part of the build process.
Get maven from this download site. This demo uses version 2.2.1.
Make sure the M2_HOME environment variable points to the installation folder, and that the maven executables directory is in the PATH, i.e., %M2_HOME%\bin.
The maven overlay method is the preferred way to build the CAS server and to maintain local configuration changes. Setting up the registries and the LDAP interface involves a couple configuration files, and maven helps to create a deployable war that includes the modified config files. You only need to install this on the machine where you'll maintain your CAS build.
Get tomcat from this download site. This demo uses version 6.0.29, and expects that you've extracted the zip file to C:\. Install tomcat on both the SSO server and the test applications server.
Once installed, edit C:\apache-tomcat-6.0.29\conf\tomcat-users.xml to add a privileged user so you can access the tomcat console.
Start tomcat and make sure no errors occur in the console. Launch a browser and navigate to http://localhost:8080 and verify that the tomcat page comes up. Access the Tomcat Manager and verify that you can login as the 'admin' user declared above. If you can do all this, your basic tomcat installation is good.
CAS can run on JBoss, but its baseline is tomcat. Tomcat starts faster and is easier to administer, so I stuck with tomcat for this demo.
Get MySQL from this download site and install it. This demo uses version 5.1.50, and I have MySQL Administrator 1.2.17. Install this on the SSO server.
Portecle is a X.509 certificate and keystore management tool, and it's a lot easier to use than the Java keytool. Get Portecle from this download site and install it everywhere. This demo uses version 1.5.
Extract the zip file to C:\, and once installed you can launch the application by double-clicking C:\Portecle\portecle.jar.
Create the X.509 Certificates
CAS uses SSL connections between the SSO server and the protected servers when performing ticket validation, passing user attributes, etc. In fact, it's recommended that SSL be used for all client and server connections since the user's authentication travels in a cookie.
This means the SSO server and all protected servers must each have a server certificate. These certificates are used to establish trust between the various clients and servers.
This demo uses self-signed certs for convenience. In production you'll want to get server certificates issued by your local Certification Authority or by a commercial CA.
Use Portecle to create a keystore and a server certificate for the CAS SSO server. Name the keystore ssoServer.jks. Set the certificate's alias to 'tomcat', and its common name (CN) to the server's fully-qualifed domain name (FQDN), e.g., ssoserver.merlin.com. Make the password for the certificate the same as the password for the keystore.
Export the server certificate to a file, e.g., ssoServer.cer, so that it can be imported into the protected server's cacerts keystore later.
Repeat the process for the server running the test applications. Name the keystore ssoClient.jks. Set the certificate's alias to 'tomcat' and its CN to the server's FQDN, e.g., ssoclient.merlin.com. Export the certificate.
On the SSO server, import the test app server's certificate into the cacerts trust store, which is located here:
The default cacerts password is 'changeit'
On the test apps server, import the SSO server's certificate into the cacerts trust store.
Configure Tomcat to Accept SSL Connections
On both server machines, edit C:\apache-tomcat-6.0.29\conf\server.xml. Uncomment the port 8443 connector and add information for the local machine's server certificate keystore, created above, including file path, password and cert alias. This is what allows the server to send its certificate to clients as part of accepting an SSL connection.
The connector element below, for the SSO server, shows that I copied my keystore into C:\apache-tomcat-6.0.29\conf. Make sure the password and alias match what was used to create the keystore and cert.
Set the connector protocol to org.apache.coyote.http11.Http11Protocol
Start tomcat and make sure no errors occur in the console. If errors occur it may be that your keystore can't be found.
Browse to the tomcat admin console, using the SSL URL containing the host's FQDN, e.g., https://ssoserver.merlin.com:8443/. If you have trouble, verify that you imported the trusted cert into the right cacerts file.
Prepare the Registry Database
On the SSO server machine, run MySQL Administrator (if you have it). Create a new schema: cas_sso. Most of the required database tables will be created by CAS during the initial system startup... except for the locks table, which is used by the registry cleaner.
Create the ticket registry locks table with the following columns:
If you have MySQL Administrator it looks like this:
Use the Maven Overlay Method to Build the SSO Server
The Starter Pom
On your server build system, create a folder to hold your local project, e.g., this demo uses C:\CAS_SSO\local-cas. Create a file, pom.xml, in that directory and copy in this xml:
Change the top level groupId, artifactId and version to whatever you need for your organization.
A few things to point out:
The Initial Server Build
This build just downloads the initial set of components, including the configuration files we'll use to create the server system. Open a console window and navigate to C:\CAS_SSO\local-cas and execute the maven command to build the project:
This will download almost a thousand files into your local repository, which by default is in C:\Documents and Settings\Your.Name\.m2\repository.
When the build completes you will find a new directory in your build folder: target. The target directory contains the build results, including the cas.war archive.
You can test the initial build by deploying this "out-of-the-box" CAS server. Copy the cas.war to C:\apache-tomcat-6.0.29\webapps. Start tomcat, browse to the Tomcat Manager admin console and verify that CAS is running.
Select the /cas application and you should see the CAS login page. Enter identical username and password ("test", "test") and the default authentication mechanism should send you to the CAS login successful page.
Configuring the SSO Server
This demo requires modifications to three of the CAS configuration files. One way to get hold of them is to copy them out of the build target directory and into a src directory where they can be modified and maintained. Another way to get them would be to check them out of the CAS repository, I guess.
Create the src directory, at the same level as target, and its sub-directories as shown below. These folders will receive the needed configuration files.
Navigate into the target directories and copy the configuration files (highlighted in the image) into their corresponding src sub-directories as listed below:
The WEB-INF\classes directory holds the log4j.xml file. If you want to modify the log4j settings for your build you can grab that file, too.
Edit cas.properties to set up Services Management
Set up the Services Management URL, and the database platform type of the services registry.
Host.name is the public domain issued and should match any https/ssl cert used.
This file holds most of the configuration settings needed for this demo. The file is attached but details follow.
The deployerConfigContext.xml file contains a set of bean definitions along with the properties they need. They include the authenticationManager bean (with properties defining credentials resolvers and authentication handlers), the contextSource bean, attributeRepository, serviceRegistryDao, etc.
Define and configure the LDAP context source
This object provides connections to the LDAP. Add as many URLs as desired to the list. Set the userDn and password to the credentials of a service account created for user lookups.
Identify the Attribute Repository
We will pass LDAP user attributes to the client. To do so we declare an attribute repository and, since the repository is our LDAP, we tell it to use the context source defined above. Edit the baseDN as needed for your domain.
The resultAttributeMapping determines which user attributes may be released to the client. In this example, the CAS Services Management and the client's Principal will both refer to the attributes by the names CN, DN and Groups.
Note that an LdapTemplate bean is used to inject a property that enables correct handling of Active Directory partial results exceptions.
Add an LDAP attribute principal resolver to the authenticationManager bean
The authenticationManager bean has a list of credentialsToPrincipalResolvers. This adds one that will do an LDAP lookup based on the sAMAccountName entered by the user, and will define the Principal available to the client application. This uses the context source and the attribute repository defined above. Edit the searchBase as needed for your directory's structure.
Add an LDAP authentication handler to the authenticationManager bean
The authenticationManager bean has a list of authenticationHandlers. This adds one that, once user lookup has been completed, will authenticate the user by opening a context using the retrieved distinguished name and the entered password. This bean also uses the context source defined above. Edit the searchBase as needed for your directory's structure.
Configure the service registry
The demo's service registry is in a MySQL database accessed via the Java Persistence Architecture (JPA) and Hibernate. The following beans specify the database type, enable automatic table creation and provide for connections to the database. Some of these beans will be shared by the ticket registry and referenced from the ticketRegistry.xml file. Edit the dataSource username and password properties as needed. (Edit deployerConfigContext.xml)
You must add the "tx" namespace to the top of the file!
Authorize users who will access Services Management
Enter the LDAP sAMAccountNames of users who will be able to run the CAS Services Management. The password is not used so just enter 'notused'.
These can't be service accounts - only normal domain user accounts
The beans providing database access for the ticket registry have already been defined
Replace the file's contents with the following or use this attached file.
The properties in the cleanerLock bean, host.name and ticket.cleaner.database.platform, are defined in cas.properties.
The Final Server Build
Now that the maven pom file and the CAS configuration files have been modified we're ready to build the deployable CAS war. Once again, open a console window and navigate to C:\CAS_SSO\local-cas and execute the maven command to build the project:
Deploy the Server
Stop tomcat if it's running, and copy the cas.war file into C:\apache-tomcat-6.0.29\webapps. Start tomcat and verify that no exceptions appear in the console.
Browse to the Tomcat Manager admin console and verify that CAS is running. Browse to the Tomcat Manager, select the /cas application and you should see the CAS login page. This time, since the "real" CAS server is running, you should be able to login using your LDAP credentials.
Enter your sAMAccountName and password and you should see the CAS login successful page.
Optional: Verify the database tables have been created
CAS will have created the rest of the database tables that it needs for the registries, or the preceding test would've failed. Still, if you feel interested you can run MySQL Administrator, go to the cas_sso schema and verify that the five service and ticket registry tables are present.
Enable the Client Services in Services Management
Browse to http://localhost:8080/cas/services/manage.html, the Services Management application. Once you login you'll see a warning to add the Management service itself as the first service. Click the 'Add New Service' button and add a service with the following URL:
If you mess up entering the service and end up unable to access Services Management, you can reset by dropping the CAS tables in the database - but don't drop the LOCKS table or you'll have to recreate it (just remove any records it may have).
Add a couple services for the test applications, Test App 1 and Test App 2. In the image below you can see I've added TestApp1 using the https URL with a wildcard that will match any page in the protected area, /sso/*. For each service, select the attributes you wish to release to the client.
Deploy the Protected Applications
This zip file contains two web applications, TestApp1 and TestApp2. Each application has an un-protected page that anyone can access and a protected servlet that users must login to access.
Download and extract the archive to C:\ on your protected server machine; it'll create C:\CasTestApp and subdirectories.
Go to the C:\CasTestApp\src directory and edit the two web.xml files there.
Go to C:\CasTestApp and execute the Deploy.bat script and it'll put together the TestApp1 and TestApp2 war files and copy them to C:\apache-tomcat-6.0.29\webapps.
All you need to do is start tomcat on the protected server and you should be ready to test.
The Test Applications
Access the test application entry points using these URLs:
The pages in the applications include links to the protected and unprotected pages of the other application. You can exercise the single sign-on function by navigating between the apps, e.g., between tabs in the same browser, between browser instances, etc.
Accessing a protected page for the first time will require user login. Once accessed, the page displays interesting information as shown below.
The protected pages have buttons for both application logout and single sign-out. Application logout invalidates the current session. Note that if you still have a valid CAS SSO login session, i.e., you're in another protected application in a different browser tab, then navigating to the protected page again will log you right back in.
Single sign-out, on the other hand, will require you to login again for any action that accesses a protected page, even refreshing the page.
CAS-ifying the Client Applications
Get the CAS Java Client
You can get the official CAS 3.1.10 client for Java from http://downloads.jasig.org/cas-clients/. Download the cas-client-3.1.10-release.zip file, which extracts to cas-client-3.1.10 and includes a modules subdirectory.
The contents of the modules directory includes jars for the CAS client classes and their dependencies. I copied all of those into the test application's WEB-INF\lib directory.
Add the CAS Filters to the Protected Applications
The web.xml file for the test applications have been modified to include the CAS filters. The order of the filters and their URL patterns (in the filter mapping elements) is important.
The URL patterns determine which pages are protected by CAS. The patterns should match what was entered into Services Management. Note that the URL pattern for the single sign-out filter matches all pages in the app.
Accessing the User Attributes
The user's LDAP attributes are added to the Principal. They can be accessed in a servlet or JSP as shown below.
Implementing Single Sign-out
The single sign-out button invokes the LogoutServlet, which contains the method shown below. It redirects to the CAS logout URL, which causes CAS to issue logout commands to all apps that are participating in the login session.