15.6.2. CAS - Central Authentication Service

This Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Central Authentication Service (CAS) Single Sign On Framework. Details about CAS can be found here.

Procedure 15.1. CAS server

  1. Set up the server to authenticate against the portal login module.
  2. Downloaded CAS from http://www.jasig.org/cas/download.
  3. Extract the downloaded file into a suitable location. This location will be referred to as CAS_DIR in the following example.
The simplest way to configure the web archive is to make the necessary changes directly into the CAS codebase.

Note

To perform the final build step and complete these instructions you will need the Apache Maven 2. Download it from here.
The CAS Server Plugin makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user.
In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is controlled by the cas.war/WEB-INF/deployerConfigContext.xml file.

Procedure 15.2. Modifying CAS server

  1. Open CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml
  2. Replace this code:
    <!--
    | Whereas CredentialsToPrincipalResolvers identify who it is some Credentials might authenticate, 
    | AuthenticationHandlers actually authenticate credentials.  Here e declare the AuthenticationHandlers that
    | authenticate the Principals that the CredentialsToPrincipalResolvers identified.  CAS will try these handlers in turn
    | until it finds one that both supports the Credentials presented and succeeds in authenticating.
    +-->
    <property name="authenticationHandlers">
    <list>
    <!--
    | This is the authentication handler that authenticates services by means of callback via SSL, thereby validating
    | a server side SSL certificate.
    +-->
    <bean class="org.jasig.cas.authentication.handler.support.HttpBasedServiceCredentialsAuthenticationHandler"
    p:httpClient-ref="httpClient" />
    <!--
    | This is the authentication handler declaration that every CAS deployer will need to change before deploying CAS 
    | into production.  The default SimpleTestUsernamePasswordAuthenticationHandler authenticates UsernamePasswordCredentials
    | where the username equals the password.  You will need to replace this with an AuthenticationHandler that implements your
    | local authentication strategy.  You might accomplish this by coding a new such handler and declaring
    | edu.someschool.its.cas.MySpecialHandler here, or you might use one of the handlers provided in the adaptors modules.
    +-->
    <bean
    class="org.jasig.cas.authentication.handler.support.SimpleTestUsernamePasswordAuthenticationHandler" />
    </list>
    </property>
    
    ...with the following:
    <!--
    | Whereas CredentialsToPrincipalResolvers identify who it is some Credentials might authenticate, 
    | AuthenticationHandlers actually authenticate credentials.  Here we declare the AuthenticationHandlers that
    | authenticate the Principals that the CredentialsToPrincipalResolvers identified.  CAS will try these handlers in turn
    | until it finds one that both supports the Credentials presented and succeeds in authenticating.
    +-->
    <property name="authenticationHandlers">
    <list>
    <!--
    | This is the authentication handler that authenticates services by means of callback via SSL, thereby validating
    | a server side SSL certificate.
    +-->
    <bean class="org.jasig.cas.authentication.handler.support.HttpBasedServiceCredentialsAuthenticationHandler"
    p:httpClient-ref="httpClient" />
    <!--
    | This is the authentication handler declaration that every CAS deployer will need to change before deploying CAS 
    | into production.  The default SimpleTestUsernamePasswordAuthenticationHandler authenticates UsernamePasswordCredentials
    | where the username equals the password.  You will need to replace this with an AuthenticationHandler that implements your
    | local authentication strategy.  You might accomplish this by coding a new such handler and declaring
    | edu.someschool.its.cas.MySpecialHandler here, or you might use one of the handlers provided in the adaptors modules.
    +-->
    <!-- Integrates with the Gatein Authentication Service to perform authentication -->
    <!--
    | Note: Modify the Plugin Configuration based on the actual information of a GateIn instance.
    | The instance can be anywhere on the internet...Not necessarily on localhost where CAS is running 
    +-->
    <bean class="org.gatein.sso.cas.plugin.AuthenticationPlugin">
    <property name="gateInHost"><value>localhost</value></property>
    <property name="gateInPort"><value>8080</value></property>
    <property name="gateInContext"><value>portal</value></property>
    </bean>
    </list>
    </property>
    
    Make sure to set the host, port and context with the values corresponding to your portal (also available in PORTAL_SSO/cas/plugin/WEB-INF/deployerConfigContext.xml).
  3. Copy PORTAL_SSO/cas/plugin/WEB-INF/lib/sso-cas-plugin-<VERSION>.jar and PORTAL_SSO/cas/plugin/WEB-INF/lib/commons-httpclient-<VERSION>.jar into the CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/lib created directory.
  4. If you have not already done so, download an instance of Tomcat and extract it into a suitable location (which will be called TOMCAT_HOME for these instructions).
  5. Edit TOMCAT_HOME/conf/server.xml and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform .

    Note

    If JBoss Enterprise Portal Platform is running on the same machine as Tomcat other ports will need to be changed in addition to 8080 in order to avoid conflicts. They can be changed to any free port. For example; you can change the admin port from 8005 to 8805 and the AJP port from 8009 to 8809.
  6. Navigate locally to the CAS_DIR/cas-server-webapp directory and execute the following command:
    mvn install
    
  7. Copy the CAS_DIR/cas-server-webapp/target/cas.war file into the TOMCAT_HOME/webapps directory.
    Tomcat should start without issue and should be accessible at http://localhost:8888/cas.

    Note

    At this stage the login functionality will not be available.

Procedure 15.3. Setup the CAS client

  1. Copy all the libraries from the PORTAL_SSO/cas/gatein.ear/lib directory into the JBOSS_HOME/server/default/deploy/gatein.ear/lib) directory.
  2. Edit the jboss-as/server/PROFILE/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml and uncomment this section:
    <authentication>
    <login-module code="org.gatein.sso.agent.login.SSOLoginModule" flag="required">
    </login-module>      
    <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required">
    <module-option name="portalContainerName">portal</module-option>
    <module-option name="realmName">gatein-domain</module-option>
    </login-module>
    </authentication>
    
    There's a line comment already in this source file to assist you.
  3. The installation can be tested at this point (assuming the CAS server on Tomcat is running):
    1. Start (or restart) JBoss Enterprise Portal Platform and direct your web browser to http://localhost:8888/cas.
    2. Login with the username root and the password gtn (or any other account created through the portal).
To utilize the Central Authentication Service, JBoss Enterprise Portal Platform needs to redirect all user authentication to the CAS server.
Information about where the CAS is hosted must be properly configured within the JBoss Enterprise Portal Platform instance. The required configuration is done by modifying three files.

Procedure 15.4. Redirect to CAS

  1. Modify the 'Sign In' link in the gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml file as follows:
    <!--
    <a class="Login" onclick="$signInAction"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>
    -->
    <a class="Login" href="/portal/sso"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>
    
  2. Modify the 'Sign In' link in the gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl file as follows:
    <!--
    <a onclick="$signInAction"><%=_ctx.appRes("UILogoPortlet.action.signin")%></a>
    -->
    <a href="/portal/sso"><%=_ctx.appRes("UILogoPortlet.action.signin")%></a>
    
  3. Replace the entire contents of gatein.ear/02portal.war/login/jsp/login.jsp with:
    <html>
    <head>
    <script type="text/javascript">
    window.location = '/portal/sso';
    </script>
    </head>
    <body>
    </body>
    </html>
    
  4. Add the following Filters at the top of the filter chain in gatein.ear/02portal.war/WEB-INF/web.xml:
    <filter>
    <filter-name>LoginRedirectFilter</filter-name>
    <filter-class>org.gatein.sso.agent.filter.LoginRedirectFilter</filter-class>
    <init-param>                                 
    <!-- This should point to your SSO authentication server -->
    <param-name>LOGIN_URL</param-name>   
    <!-- If casRenewTicket param value of InitiateLoginServlet is:  not specified or false -->
    <param-value>http://localhost:8888/cas/login?service=http://localhost:8080/portal/private/classic</param-value>
    <!-- If casRenewTicket param value of InitiateLoginServlet is : true -->
    <!-- <param-value>http://localhost:8888/cas/login?service=http://localhost:8080/portal/private/classic&amp;renew=true</param-value> -->
    </init-param>
    </filter>
    <filter>
    <filter-name>CASLogoutFilter</filter-name>
    <filter-class>org.gatein.sso.agent.filter.CASLogoutFilter</filter-class>
    <init-param>
    <!-- This should point to your JOSSO authentication server -->
    <param-name>LOGOUT_URL</param-name>
    <param-value>http://localhost:8888/cas/logout</param-value>
    </init-param>
    </filter>
    <!-- Mapping the filters at the very top of the filter chain -->
    <filter-mapping>
    <filter-name>LoginRedirectFilter</filter-name>
    <url-pattern>/*</url-pattern>
    </filter-mapping>
    <filter-mapping>
    <filter-name>CASLogoutFilter</filter-name>
    <url-pattern>/*</url-pattern>
    </filter-mapping>
  5. Replace the InitiateLoginServlet declaration in gatein.ear/02portal.war/WEB-INF/web.xml with:
    <servlet>
    <servlet-name>InitiateLoginServlet</servlet-name>
    <servlet-class>org.gatein.sso.agent.GenericSSOAgent</servlet-class>
    <init-param>
    <param-name>ssoServerUrl</param-name>
    <param-value>http://localhost:8888/cas</param-value>
    </init-param>    
    <init-param>
    <param-name>casRenewTicket</param-name>
    <param-value>false</param-value>
    </init-param>
    </servlet>
    
Once these changes have been made, all links to the user authentication pages will redirect to the CAS centralized authentication form and CAS can be used as an SSO implementation in your portal.