URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.1/origin/InstallationCAS.html
Author: Fabio Poroli, SWITCH
Contact: aai@switch.ch
Version: 1.0 - 20040316

Installation of Shibboleth Origin with Web Single Sign On (SSO)

A SSO system brings following advantages compared to a plain Shibboleth-Apache installation:
  1. Authentication can be done through a normal HTML page.
  2. After a successful login a session cookie is sent to the client's browser and as long as the cookie remains valid requests to other resources wont require  further authentication.
There are different existing SSO systems depending on the internet server architecture. An overview of existing SSO systems can be found here. In our case we opted for a Java servlet based solution, CAS, an open source implementation of YALE university. Using CAS there is no real need any more to install the Apache Webserver because the authentication is now done in CAS itself and Tomcat can handle SSL connections as well.
 
The installation follows the usual steps:

-> Debian -> Java -> Tomcat

The most tricky part of the installation is the security set-up. With Tomcat we need only one key and it should look like this (using a tool like SSKeyTool) :

Shows the construction of the key

To create the keystore follow the same setup instructions as described in the Shibboleth Origin installation guide (Chapter 2.4).

The Tomcat configuration file conf/server.xml look like the following:

<Server port="8005" shutdown="SHUTDOWN" debug="0">
        <Service name="Tomcat-Standalone">

                <!-- Http Conncector -->

                <Connector className="org.apache.catalina.connector.http.HttpConnector" port="8080" minProcessors="5" maxProcessors="75" 
                           redirectPort="443" acceptCount="10" debug="0"/>
                <Connector className="org.apache.catalina.connector.http.HttpConnector" port="80" minProcessors="5" maxProcessors="75" 
                           redirectPort="443" acceptCount="10" debug="0"/>

                <!-- Https Connector -->

                <Connector className="org.apache.catalina.connector.http.HttpConnector" port="443" minProcessors="5" maxProcessors="75" 
                           enableLookups="true" redirectPort="8443" acceptCount="10" debug="0" connectionTimeout="60000" scheme="https" 
                           secure="true">
                        <Factory className="org.apache.catalina.net.SSLServerSocketFactory" clientAuth="false" protocol="TLS" 
                                 keystoreFile="/etc/opt/jakarta-tomcat-4.1.29/shibboleth-origin-1.1/keystore.jks" keystorePass="STOREPASS"/>
                </Connector>

                <Engine name="Standalone" defaultHost="localhost" debug="0">
                        <Logger className="org.apache.catalina.logger.FileLogger" prefix="catalina_log." suffix=".txt" timestamp="true"/>
                        <Realm className="org.apache.catalina.realm.MemoryRealm" />
                        <Host name="localhost" debug="0" appBase="webapps" unpackWARs="true" autoDeploy="true">
                                <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log." 
                                       suffix=".txt" pattern="common" resolveHosts="false"/>
                                <Logger className="org.apache.catalina.logger.FileLogger" directory="logs" prefix="localhost_log." 
                                        suffix=".txt" timestamp="true"/>
                        </Host>
                </Engine>
        </Service>
</Server>

This way both the conf/server.xml as well as the Shibboleth file origin.properties point to the same keystore.

Once this is done and Shibboleth has been deployed we need to install CAS. The Installation of CAS is done this way: the client part is a simple JAR file and needs to be moved to $CATALINA_HOME/common/endorsed directory; the server part is a WAR file and as usual it needs to be deployed in the web application directory as described in the documentation.

When a user tries to access a resource that requires Shibboleth authentication the user is redirected by the resource to the WAYF and the WAYF sends the user to the corresponding Handle Servlet of the home organisation.
Using a so called Java filter, Tomcat can intercept the request to the Handle Servlet and check the authentication status of the request. If the user was not authenticated before, he is sent to the CAS authentication servlet.
We have the following schema:

Workflow CAS
   
This means:

. If somebody wants to access a resource through Shibboleth, he is redirected to the Shibboleth Handle Servlet.
. Before somebody can access the Handle Servlet two filters need to be passed:
  1. CAS-Filter: Has the user  already authenticated himself?
    - No    The request is redirected to the CAS-Servlet where a login page is presented to the user.
    - Yes   The user is allowed to access the second filter.

  2. Security-Wrapper: this filter implements the security features needed by the Shibboleth Handle Servlet. Shibboleth expects a different authentication system (using the so called "user principal") as opposed to the system offered by CAS (authentication through session cookie). This filter provides the security information requested by Shibboleth in a transparent way.
The web.xml file of Shibboleth should then look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
    <description>SWITCH Shibboleth Web-Application</description>

    <filter>
        <filter-name>CASFilter</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://call-ho.switch.ch/cas/login</param-value>
        </init-param>
        <init-param>
            <param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name>
            <param-value>https://call-ho.switch.ch/cas/proxyValidate</param-value>
        </init-param>
        <init-param>
            <param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
            <param-value>call-ho.switch.ch</param-value>
        </init-param>
    </filter>

    <filter>
        <filter-name>ShibFilter</filter-name>
        <filter-class>ch.SWITCH.aai.shibcasfilter.ShibCasFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>CASFilter</filter-name>
        <url-pattern>/HS/*</url-pattern>
    </filter-mapping>

    <filter-mapping>
        <filter-name>ShibFilter</filter-name>
        <url-pattern>/HS/*</url-pattern>
    </filter-mapping>

    <servlet>
        <servlet-name>HS</servlet-name>
        <display-name>Shibboleth Handle Service</display-name>
        <servlet-class>edu.internet2.middleware.shibboleth.hs.HandleServlet</servlet-class>
        <init-param>
            <param-name>OriginPropertiesFile</param-name>
            <param-value>file:///etc/opt/jakarta-tomcat-4.1.29/shibboleth-origin-1.1/origin.properties</param-value>
        </init-param>
    </servlet>

    <servlet>
        <servlet-name>AA</servlet-name>
        <display-name>Shibboleth Attribute Authority</display-name>
        <servlet-class>edu.internet2.middleware.shibboleth.aa.AAServlet</servlet-class>
        <init-param>
            <param-name>OriginPropertiesFile</param-name>
            <param-value>file:///etc/opt/jakarta-tomcat-4.1.29/shibboleth-origin-1.1/origin.properties</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>HS</servlet-name>
        <url-pattern>/HS</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>AA</servlet-name>
        <url-pattern>/AA</url-pattern>
    </servlet-mapping>

    <mime-mapping>
        <extension>css</extension>
        <mime-type>text/css</mime-type>
    </mime-mapping>
</web-app>


The security wrapper filter is composed by following two files:

    ShibCasFilter.java
    LoginRequestWrapper.java

The user authentication in CAS can be solved in different ways. One of the most standard ways is to authenticate users against a LDAP server. In our special case we used an IMAP server. For CAS exists, however, different kind of plugins, like LDAP, NIS, ...
If you are interested you can see the authentication code in the following two files:

    LdapAuthentication
    ImapAuthentication 

The CAS Servlet need to be informed of the authentication method used. Please adapt the file WEB-INF/web.xml as follows:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">

<web-app>

  <description>
    Central Authentication Service (CAS)
  </description>

  <!-- Initialization -->

    <!-- Authentication handler -->
    <context-param>
        <param-name>edu.yale.its.tp.cas.authHandler</param-name>
        <param-value>ch.SWITCH.aai.imappasswordhandler.ImapPasswordHandler</param-value>
    </context-param>
	
    ...


Finally we cam personalize our login page in cas/login.jsp to look like something so:

Login Page