Central Authentication Service Configuration

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Table of Contents

• 1 PLEASE READ FIRST: IMPORTANT NOTE
  
  
  
  • 1.1 Introduction
  
  
  • 1.2 Getting Started
  
  
  • 1.3 Assumptions
  
  
  • 1.4 Add the CAS Client Filter to Alfresco
    
    
    
    • 1.4.1 Testing CAS Protection
    
    
  
  
  • 1.5 Configuring SSO between CAS and Alfresco
    
    
    
    • 1.5.1 Configure Alfresco's Authentication Filter in web.xml
    
    
    • 1.5.2 Add the CAS Authentication Filter jar file
    
    
  
  
  • 1.6 Test Single Sign On
    
    
    
    • 1.6.1 Troubleshooting
    
    
  
  
  • 1.7 Add the CAS Client Filter to Alfresco Share
    
    
    
    • 1.7.1 Testing CAS Protection
    
    
    • 1.7.2 Configure Alfresco's Authentication Filter in web.xml
    
    
    • 1.7.3 Troubleshooting
    
    
  
  
  • 1.8 Issues
    
    
    
    • 1.8.1 Admin Users
    
    
    • 1.8.2 Guest Users
    
    
    • 1.8.3 Other Servlets
    
    
  
  

PLEASE READ FIRST: IMPORTANT NOTE

An alternative solution that does not involve editing web.xml is recommended on the page Alfresco With mod_auth_cas.

Introduction

This page is a installation guide that is intended for users who don't want to do any coding.

There is a lot of activity on the forums on getting CAS working with Alfresco, so we are posting these instructions to get you going as quickly as possible so you can impress your bosses with the least amount of work. It doesn't pretend to cover all dimensions but it should help you understand what is going on. And of course your colleagues will 'worship you like a god' as they say over at JA-SIG http://www.ja-sig.org/wiki/display/CA.../Demo.

Its actually turned out a bit long winded so please feel free to make a snappier how-to if you find this useful.

Getting Started

Before you start with these instructions you must make sure you have a working CAS Server installation and a working Alfresco installation, preferably installed in separate container instances (ie separate Tomcat, JBoss etc). Being on a tight budget we run them both on the same server, but you can do it on two for maximum effect and minimum mucking about with mod_jk and ports.

Install CAS Server and Client

Install CAS by following the instructions that come with CAS, or the following quick start guide http://www.ja-sig.org/wiki/display/CASUM/Demo

Make sure you go the whole hog and make CAS work with two separate Tomcat instances - one for the server and one for the client. This will ensure that the JVMs have all the right security certificates in place for the back channel SSL connections.

One timesaver to note is that if you are running CAS Server and Alfresco on the same file system using the same Java installation then you can skip Step 13 Establish trust with CAS SSO Server where you are supposed to compile and run the java code in the Demo example. This is because both JVMs share the same certificates. Just don't forget to add the following JAVA_OPTS argument to the Tomcat startup script.

-Djavax.net.ssl.trustStore=/root/.keystore

I just checked back and that part does not appear in the CAS instructions. I had to do it, but there are a few differences in the environments (eg the CAS instructions assumes windows and we did it on Ubuntu Linux).

Install Alfresco

If you are reading this you probably have Alfresco up and running. ...don't you?.

Also, it is a good idea to make a backup of the entire Alfresco Tomcat installation, just in case you make too many mistakes and need to blow the whole thing away (I know - this has happened to me!). Note that the install process adds and modifies files in other parts of the file system, so even a clean deploy of the alfresco.war web app may not get you back to a working application.

Assumptions

This section lists the assumptions about names, addresses and locations that may be different on your system. First thing to note is that we are running two instances of Tomcat on the same server, and using virtual hosts plus mod_jk in apache to provide the two host names. This means that the two tomcat instances must use unique ports for their three connectors - http, https and ajp (the latter is the mod_jk connector). I use the defaults for the CAS tomcat ports and add one to the port number get the equivalent Alfresco Tomcat port.

• Unix hostname of the server cms
  

• DNS hostname of the CAS server cas.keembay.com
  
• path to alfresco tomcat installation /opt/alfresco/tomcat
  
• HTTP port number of the CAS tomcat 8080
  
• HTTPS port number of the CAS tomcat 8443
  
• AJP port number of the CAS tomcat 8009
  

• DNS  hostname of the Alfresco server alfresco.keembay.com
  
• path to CAS tomcat installation /opt/cas/tomcat
  
• username in Alfresco admin, password admin
  
• HTTP port number of the Alfresco tomcat 8081
  
• HTTPS port number of the Alfresco tomcat 8444
  
• AJP port number of the Alfresco tomcat 8010
  

Add the CAS Client Filter to Alfresco

First thing, edit the alfresco web.xml to add the filter definitions.

root@cms# vi /opt/alfresco/tomcat/webapps/alfresco/WEB-INF/web.xml

Look for the first <filter> tag and immediately before it put the following stanzas. Note, there is a difference between this and the one in the instructions for installing the CAS Client on the CAS Tomcat. The last init-param of the CAS filter must be set to the hostname of the server to be CAS-ified, e.g. alfresco.keembay.com. If you are accessing Tomcat directly via an alternate port (e.g. 8081) as opposed to via apache/mod_jk you will need to add the port number to the hostname.

 <!-- CAS client filter -->
 <filter>
     <filter-name>CAS Filter</filter-name>
     <filter-class>edu.yale.its.tp.cas.client.filter.CASFilter</filter-class>
     <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.loginUrl</param-name>
         <param-value>https://cas.keembay.com:8443/cas/login</param-value>
     </init-param>
     <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name>
         <param-value>https://cas.keembay.com:8443/cas/serviceValidate</param-value>
     </init-param>
     <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
         <param-value>alfresco.keembay.com</param-value>
     </init-param>
 </filter>

 <filter-mapping>
     <filter-name>CAS Filter</filter-name>
     <url-pattern>/faces/*</url-pattern>
 </filter-mapping>
 <!-- end of CAS client filter -->
 

Next, copy the CAS Client jar file into the alfresco webapp lib folder. If you have CASified the servlets-examples webapp as in [http://www.ja-sig.org/wiki/display/CA.../Demo] then the jar will be in the webapp:

root@cms# cd /opt/cas/tomcat/webapps/servlets-examples/WEB-INF/lib/
root@cms# cp casclient-2.1.1.jar /opt/alfresco/tomcat/webapps/alfresco/WEB-INF/lib
root@cms# chown alfresco:alfresco /opt/alfresco/tomcat/webapps/alfresco/WEB-INF/lib/*

Otherwise you have to get it from the CAS Server software distributions. I'm not sure of the reasoning behind this, but the cas-client software distro does not seem to be required - the jar is in the war file in the server distro.

get the tarball in your home directory and untar it, unzip the war file and copy out casclient-2.1.1.jar like this:

root@cms# tar -xzf cas-server-3.2.1-release.tar.gz 
root@cms# cd cas-server-3.2.1/modules
root@cms# unzip cas-server-webapp-3.2.1.war
root@cms# cp WEB-INF/lib/casclient-2.1.1.jar /opt/alfresco/tomcat/alfresco/WEB-INF/lib
root@cms# chown alfresco:alfresco /opt/alfresco/tomcat/webapps/alfresco/WEB-INF/lib/*

Testing CAS Protection

To test what you have done so far bounce the alfresco tomcat. Monitor the logs and wait...

That's the first step - adding CAS protection to Alfresco. You can try it at this point opening http://alfresco.keembay.com/alfresco in a browser.
Before you do, make sure you don't have a CAS session hanging around from earlier testing. To do this, clear your cookies and/or shut down the browser.

You should see the CAS login screen, and when you log in (eg with admin/admin) you should be redirected back to the My Alfresco Dashboard.

If this happens you have successfully protected alfresco with CAS, but you do not yet have single sign on - (i.e. you will not be logged into alfresco - that needs yet more changes to the guts of Alfresco!)

Nevertheless this is an achievement - give your favourite signal of triumph, sit back for a moment and admire your work. The next bit is tricky.

Configuring SSO between CAS and Alfresco

Well its not that bad - this is where you have to replace the built in Alfresco authentication. Alfresco must leave authentication to CAS and trust all requests that make it through the CAS filter. Alfresco must take the username from an attribute in the servlet session which is placed there by the CAS Filter.

To do this you have to change the Java code that is run when a user hits an alfresco page, and this disables the form based login page of Alfresco.

Configure Alfresco's Authentication Filter in web.xml

You need to edit web.xml again: /opt/alfresco/tomcat/webapps/alfresco/WEB-INF/web.xml

Note that these edits are in a different place from the edits above - leave what you have already done alone and edit the filter named 'Authentication Filter'. Locate the following lines:

<filter>
    <filter-name>Authentication Filter</filter-name>
    <filter-class>org.alfresco.web.app.servlet.AuthenticationFilter</filter-class>

and edit them to become

  <filter>
    <filter-name>Authentication Filter</filter-name>
    <filter-class>com.keembay.alfresco.web.app.servlet.CASAuthenticationFilter</filter-class>
    <init-param>
        <param-name>cas.user.label</param-name>
        <param-value>edu.yale.its.tp.cas.client.filter.user</param-value>
    </init-param>

Where the bold text is different or added. This tells tomcat to use your new code to authenticate the user, simply by grabbing the username out of the session. The code assumes that the username is present, since the CAS Filter should prevent any requests from hitting Alfresco without it. If you disable the CAS Filter and requests get through to the repository code without the user populated, it might not be pretty!

Add the CAS Authentication Filter jar file

You now need to put keembay-alfresco-cas.jar into the classpath

root@cms# cp keembay-alfresco-cas.jar /opt/alfresco/tomcat/webapps/alfresco/WEB-INF/lib

I can't attach files to this wiki page so its here: http://keembay.com/alfresco/extras/keembay-alfresco-cas.jar . It was compiled for Java 1.5 against the Alfresco 2.1 community source so it should work for you.

If you get issues then you can try to compile it from source. http://keembay.com/alfresco/extras/CASAuthenticationFilter.java

There a few ways to skin that cat.

1. You can grab the complete alfresco source code from SVN, and build the whole thing using ant. Use a search tool to find find AuthenticationFilter.java then put CASAuthenticationFilter.java  in the same source tree, in the correct package folder. In my version that makes it
   

./root/projects/web-client/source/java/com/keembay/alfresco/web/app/servlet/CASAuthenticationFilter.java

Once you rebuild, this file will get compiled and you can search for the resulting class file.

1. If that sounds like too much downloading and buiding trouble the alternative is to create your own Java project in your favourite IDE, add all the jar files from /opt/alfresco/tomcat/webapps/alfresco/WEB-INF/lib then compile CASAuthenticationFilter.java.
   

Either way, once you are done, jar it up and put it into the webapp as above or put the class file in /opt/alfresco/tomcat/webapps/alfresco/WEB-INF/classes/com/keembay/alfresco/web/app/servlet

Test Single Sign On

Once you have web.xml and CASAuthenticationFilter.class in place you can restart alfresco and see what happens.

What should happen is that you open alfresco and get redirected to CAS as before. Enter the username of a known Alfresco user (eg admin) with a password that is the same as the username (irrespective of what the real password in alfresco is) and you should get into Alfresco. This time you should see Logout (admin) in the top right of the Alfresco page indicating that you have sucessfully logged in.

As usual monitor the logs in case something goes wrong, and use your skill and judgement to track down the errors.

Troubleshooting

• Alfresco doesn't start
  
  • typo in the markup in web.xml - double check it, validate in an XML editor. Failing that restore the original that you backed up, make babystep changes and restart Alfresco after each change
    
  • file permission errors. Make sure all files are owned by the alfresco user with chown -R alfresco:alfresco /opt/alfresco/tomcat/*
    
  • study catalina.out for inspiration
    
• Class not found
  
  • the classname in the <filter-class> tag is wrong
    
  • the .class file is in the wrong place
    
  • you used the .java instead of the .class file
    
• CAS : Filter init-param named cas.user.label not found in web.xml
  
  • error in the init-param name
    
  • xml snipped in the wrong place
    
  • commented out etc
    
• CAS : Attribute named edu.yale.its.tp.cas.client.filter.user not found in the session.
  
  • mismatch in edu.yale.its.tp.cas.client.filter.user between CAS and the init-param/param-value in web.xml
    
• org.alfresco.repo.security.authentication.AuthenticationException: Could not find user by userName: mike
  
  • you have attempted to log into CAS with a username that is not known to Alfresco
    
• HTTPS exceptions in the logs
  
  • your self signed certificate that you created when setting up the CAS server is invalid - this is usually because the domain name you are running CAS from is different to the name on the certificate. You must enter the dns hostname (eg cas.keembay.com) when you are prompted for your first and last name. Seriously, as in:
    

What is your first and last name?
  [Unknown]:  cas.keembay.com

However - if you were able to casify servlets-examples and you have not changed the hostname then this should not be the problem. If you do regenerate the certificates then you must restart all the tomcat servers so that Java uses the latest ones.

That's just a few things that can go wrong - each small step in all this is fairly simple to do but there's a lot steps and its not that easy to troubleshoot if you run into problems, so good luck!

Anyway this should get a lot easier when Alfresco plays nice with CAS out of the box.

Add the CAS Client Filter to Alfresco Share

The following changes have been implemented on 4.2.d.

root@cms# vi /opt/alfresco/tomcat/webapps/share/WEB-INF/web.xml

Look for the first <filter-mapping> tag and immediately before it put the following stanzas, this is every similar to the directions above for /alfresco. The main difference here is that we are going to protect /* instead of /faces/*.

 <!-- CAS client filter -->
 <filter>
     <filter-name>CAS Filter</filter-name>
     <filter-class>edu.yale.its.tp.cas.client.filter.CASFilter</filter-class>
     <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.loginUrl</param-name>
         <param-value>https://cas.keembay.com:8443/cas/login</param-value>
     </init-param>
     <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name>
         <param-value>https://cas.keembay.com:8443/cas/serviceValidate</param-value>
     </init-param>
     <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
         <param-value>alfresco.keembay.com</param-value>
     </init-param>
 </filter>

 <filter-mapping>
     <filter-name>CAS Filter</filter-name>
     <url-pattern>/*</url-pattern>
 </filter-mapping>
 <!-- end of CAS client filter -->
 

Copy the CAS Client jar file into the appropriate place for share from above:

root@cms# cd /opt/cas/tomcat/webapps/servlets-examples/WEB-INF/lib/
root@cms# cp casclient-2.1.1.jar /opt/alfresco/tomcat/webapps/share/WEB-INF/lib
root@cms# chown alfresco:alfresco /opt/alfresco/tomcat/webapps/share/WEB-INF/lib/*

Changing web-extention to accept authentication from CAS

root@cms# vi /opt/alfresco/tomcat/webapps/shared/classes/alfresco/web-extension

Look for a large block of with SsoUserHeader inside of the comment blocks, this appears to change fairly often

 <!-- CAS client filter -->
 <filter>
     <filter-name>CAS Filter</filter-name>
     <filter-class>edu.yale.its.tp.cas.client.filter.CASFilter</filter-class>
     <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.loginUrl</param-name>
         <param-value>https://cas.keembay.com:8443/cas/login</param-value>
     </init-param>
     <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name>
         <param-value>https://cas.keembay.com:8443/cas/serviceValidate</param-value>
     </init-param>
     <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
         <param-value>alfresco.keembay.com</param-value>
     </init-param>
 </filter>

 <filter-mapping>
     <filter-name>CAS Filter</filter-name>
     <url-pattern>/*</url-pattern>
 </filter-mapping>
 <!-- end of CAS client filter -->
 

Testing CAS Protection

To test what you have done so far bounce the share tomcat. Monitor the logs and wait... I prefer to bounce all of alfresco on a test enviornment to verify that everything works on a cold start.

You can try the CAS protection, first clear your cas session via private browsing, clearing cookies, or restarting your browser. Open http://alfresco.keembay.com/share in a browser and you should be directed to CAS login page. Upon successful login you should be directed into alfresco share dashboard.

Configure Alfresco's Authentication Filter in web.xml

You need to edit web.xml again: /opt/alfresco/tomcat/webapps/alfresco/WEB-INF/web.xml

Note that these edits are in a different place from the edits above - leave what you have already done alone and edit the filter named 'Authentication Filter'. Locate the following lines:

<filter>
    <filter-name>Authentication Filter</filter-name>
    <filter-class>org.alfresco.web.app.servlet.AuthenticationFilter</filter-class>

and edit them to become

  <filter>
    <filter-name>Authentication Filter</filter-name>
    <filter-class>com.keembay.alfresco.web.app.servlet.CASAuthenticationFilter</filter-class>
    <init-param>
        <param-name>cas.user.label</param-name>
        <param-value>edu.yale.its.tp.cas.client.filter.user</param-value>
    </init-param>

Where the bold text is different or added. This tells tomcat to use your new code to authenticate the user, simply by grabbing the username out of the session. The code assumes that the username is present, since the CAS Filter should prevent any requests from hitting Alfresco without it. If you disable the CAS Filter and requests get through to the repository code without the user populated, it might not be pretty!

Troubleshooting

• See above with /alfresco troubleshooting so we are not duplicating documentation
  
• 302 or 301 redirect /alfresco may be configured to protect /* instead of /faces/* this is in other documentation online for alfresco casification.
  
• Turn on debugging and look for strange http error codes for ideas on what to open up such as the API
  

Issues

Admin Users

After installing CAS on Alfresco and logging in as admin, some admin users options are not available. Probably due to another filter - 'Admin Authentication Filter' hiding the user management features. The filter mapping includes /faces/jsp/users/users.jsp which is a big clue. The solution will be to find out from the Alfresco engineers what the filter does and ensure that admin users are allowed to access the page as usual even if the user has authenticated using CAS.

I suspect that the standard Alfresco login process stores something else in the session that indicates that the user is an admin that our CASAuthenticationFilter does not. If the Alfresco engineers can help with that we will be happy to update our code and repost.

Guest Users

Another point is that these instructions protect everything with CAS so you can't get into Alfresco as a guest. This is another potential enhancement to the CAS filters and their config in web.xml. It would be to protect the login page with CAS but leave the rest of Alfresco accessible so that it can handle anonymous access correctly but force login via CAS. Again the Alfresco engineers might be able to help...

Other Servlets

both CAS and Alfresco use a URL parameter 'ticket' as part of the authentication mechanism, and one clashes with the other. As a result Alfresco sees a 'ticket' parameter, and fails to validate it because it is a CAS ticket not an alfresco ticket.

This is not an issue for the web interface to Alfresco but trips up the other servlets which detect the ticket parameter and try to authenticate it. That means CAS won't work with the various servlets for download, templates, commands, ajax, etc... unless you change some more Java code.
Web Client
Customizing and Extending
Authentication
Installation
Configuration