⁠Chapter 12. Single Sign-on

12.1. File Name Conventions
12.2. Single Sign-on (SSO) Configuration
12.3. Central Authentication Service (CAS)
12.3.1. Authentication Process with Central Authentication Service integration
12.3.2. Logging out Process with Central Authentication Service integration
12.3.3. Configuration Result
12.4. Configuration for Central Authentication Service (CAS)
12.4.1. Downloading Central Authentication Service
12.4.2. Modifying the Central Authentication Service (CAS) Server
12.4.3. Authentication Plugin for Central Authentication Service (CAS)
12.4.4. Configuring the Authentication Plugin
12.4.5. Setting up Logout Redirection
12.4.6. Cookie Configuration for Central Authentication Service (CAS) Single Sign-on
12.4.7. Portal Authentication using Central Authentication Service Ticket Granting Cookie (CASTGC)
12.4.8. Installing Apache Tomcat Server
12.5. Modifying the Portal
12.5.1. Configuring Portal Single Sign-on
12.5.2. Configuration properties for Portal Single Sign-on
12.6. Building and Deploying Central Authentication Service (CAS)

⁠12.1. File Name Conventions

The following naming conventions are used in file paths to improve their readability. Each convention is styled so that it stands out from the rest of the text. Where you see [version], replace this with the current version of the portal when reading the directory locations.
CAS_DIR
The installation root of the Central Authentication Service (CAS) single sign-on framework. This directory is an arbitrary location chosen when CAS is downloaded and installed.
This convention is mentioned in the Administration and Configuration guide chapter SSO_Single_Sign_On_-Central_Authentication_Service
ID_HOME
The JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/ directory, which contains identity-related configuration resources.
This convention is mainly used in LDAP_Integration in Administration and configuration guide.
JPP_DIST
The installation root of the portal instance. For example, if the portal distribution archive is extracted to the /opt/jboss/RHJP/ directory, the JPP_DIST directory is /opt/jboss/RHJP.
This directory contains the jboss-jpp-[version];, gatein-management and gatein-sso directories, and is used extensively in sections that contain configuration stored in these directories.
JPP_HOME
The JPP_DIST/jboss-jpp-[version]; directory, which contains the application server and the configuration files necessary to run the portal.
This directory contains the gatein, modules and standalone directories.
TOMCAT_HOME
The installation root of the Apache Tomcat server. Apache Tomcat is a simple Java-based web server that can host servlets or JSP applications. It is not a part of the portal, however, it is used in various examples in this guide to host single sign-on authentication services.

See Also:

Report a bug

⁠12.2. Single Sign-on (SSO) Configuration

The portal provides an implementation of single sign-on (SSO) as an integration and aggregation platform.
When logging into the portal, users can access many systems through portlets using a single identity. In many cases, however, the portal infrastructure must be integrated with other SSO enabled systems.
There are many different Identity Management solutions available. In most cases each SSO framework provides a unique way to plug into a Java EE application.
This section will cover the implementation of four different SSO plug-ins with the portal:
  • Central Authentication Service.
  • Java Open Single Sign-on.
  • OpenAM.
  • Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO).
In this tutorial, the SSO server is being installed in a Tomcat environment.
All the packages required for SSO setup can be found in the JPP_DIST/gatein-sso directory of the portal binary package.

Warning

Users are advised to not run any portal extensions that could override the data when manipulating the gatein.ear file directly.

See Also:

Report a bug

⁠12.3. Central Authentication Service (CAS)

The CAS single sign-on (SSO) plug-in enables seamless integration between the platform and the CAS SSO framework. General information about CAS can be found on the Jasig website.
Report a bug

⁠12.3.1. Authentication Process with Central Authentication Service integration

The authentication process with CAS integration occurs in the following order:
  1. A user visits the main portal page, and wishes to authenticate. The user clicks Sign in.
  2. Normally this action would present the portal login dialog, however with SSO integration enabled, the action redirects the user to a marker URL such as http://localhost:8080/portal/sso.
    The portal handles this user action by calling the interceptor (Servlet filter) LoginRedirectFilter, which redirects the user seamlessly away from the /portal/sso URL to the CAS server page.
  3. The interceptor redirects the user to the CAS login page http://localhost:8888/cas/login. The user enters the correct authentication information, and submits the form.
    The CAS server retrieves the information from the identity store. The store could be an external database, a LDAP server, or from information obtained through an authentication plug-in such as the one shipped with the portal.
  4. Once CAS determines the user has the correct access privileges to access the portal server, CAS redirects the user back to the portal through another marker URL such as http://localhost:8080/portal/initiatelogin.
    The InitiateLoginFilter interceptor acts on the user redirection to /portal/initiatelogin by obtaining a CAS ticket attached in the HTTP request inside the ticket parameter. The interceptor then delegates validation of this ticket to a configured CASAgent component.
  5. The CASAgent validates the ticket by sending a validation request to the CAS server through a configured back channel. The CAS server validates the request, and ensures it contains the user name of the authenticated user in step 3.
  6. After SSO validation, InitiateLoginFilter redirects the user to the portal login URL http://localhost:8080/portal/login, which initiates JAAS authentication.
    The SSOLoginModule detects whether the user has been successfully validated by CASAgent. If this is the case, the login module obtains data about user (groups, memberships) from OrganizationService and encapsulates the details into an Identity object.
  7. JBoss Portal completes the authentication request by establishing the JAAS Subject, and saves the roleIdentity object to the IdentityRegistry.
  8. After successful JAAS authentication, the user is redirected to the portal in an authenticated state.
For more information about the available Login Modules shipped with the product, see the Red Hat JBoss Application Platform Security Guide.

See Also:

Report a bug

⁠12.3.2. Logging out Process with Central Authentication Service integration

The logout process with CAS integration occurs in the following order:
  1. The authenticated user clicks the Sign out link.
  2. The CASLogoutFilter interceptor recognizes the logout request, and redirects the user to the CAS logout page http://localhost:8888/cas/logout.
  3. The CAS server logs out the user, and invalidates the CAS cookie CASTGC.
  4. CAS redirects the user back to the portal using the logout redirection.
    If the CASLogoutFilter is enabled, the user is logged out from both the portal and CAS server.
  5. The logout redirection request completes the logout process on the CAS server's side, and the user is redirected to the portal's anonymous page.

See Also:

Report a bug

⁠12.3.3. Configuration Result

For scope purposes, the setup instructions assume the following configuration outcomes:
  • The CAS 3.5 is downloaded, and required changes are made to authentication plug-in, logout redirection, and CASTGC cookie configuration.
  • Once configured, Apache Maven is used to create the custom CAS web archive, suitable for deployment.
  • The WAR is deployed to the Apache Tomcat server, which acts as the host for the CAS.
  • Apache Tomcat is configured to listen on localhost:8888.
  • The portal is configured to listen on localhost:8080.
Report a bug

⁠12.4. Configuration for Central Authentication Service (CAS)

⁠12.4.1. Downloading Central Authentication Service

CAS can be downloaded from http://www.jasig.org/cas/download. The supported version is CAS 3.5. More recent CAS versions may also work, however have not been officially tested as part of this specific configuration exercise.
Extract the downloaded file into a suitable directory location. This location will be referred to as CAS_DIR in subsequent configuration instructions.
Report a bug

⁠12.4.2. Modifying the Central Authentication Service (CAS) Server

To configure the CAS server correctly, the most effective way is to make the necessary changes directly in the CAS code base. Follow the instructions in the sections below to make the required changes to the CAS code base, before using Maven to build the CAS web archive.
Report a bug

⁠12.4.3. Authentication Plugin for Central Authentication Service (CAS)

While it is possible (and perfectly acceptable) for an administrator to configure CAS to retrieve user credentials from an external database, or from a LDAP server, it is also possible to use JBoss technology.
CAS can be configured to make secure authentication callbacks to a RESTful service installed on the remote portal instance using the supplied CAS AuthenticationPlugin.
Implementing the AuthenticationPlugin on the CAS server has the advantage of leveraging a single identity storage for portal user, group and role data. If a new user is added using the portal user management interface, the user information is instantly accessible to the CAS server through the technology implemented by the AuthenticationPlugin.
The plug-in verifies user credentials by connecting to an existing portal instance using REST over the HTTP protocol. The portal serves a REST authentication callback request, and verifies the user identity against the portal's own identity storage provided by the PicketLink IDM OrganizationService. The AuthenticationPlugin receives the portal's response to the CAS server, and continues with the authentication process based on user data in the response.
Report a bug

⁠12.4.4. Configuring the Authentication Plugin

For the plug-in to function correctly, it must be properly configured on the CAS server to connect to this service. Set up the server to authenticate against the portal using the REST call-back.
⁠

Procedure 12.1. Configuring the Authentication Plug-in

  1. Open CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml.
  2. Replace the default configuration, which declares the Jasig SimpleTestUsernamePasswordAuthenticationHandler Authentication Handler with the following supported Authentication Handler. 
    ​<bean class="org.gatein.sso.cas.plugin.AuthenticationPlugin">
​  <property name="gateInProtocol"><value>http</value></property>
​  <property name="gateInHost"><value>localhost</value></property>
​  <property name="gateInPort"><value>8080</value></property>
​  <property name="gateInContext"><value>portal</value></property>
​  <property name="httpMethod"><value>POST</value></property>
​</bean>

    Note

    This configuration is available in the JPP_DIST/gatein-sso/cas/plug-in/WEB-INF/deployerConfigContext.xml file. If you choose to take this configuration file, ensure the default host, port and context parameters are adjusted to match the values corresponding to the remote portal instance.
  3. Copy all jars from JPP_DIST/gatein-sso/cas/plug-in/WEB-INF/lib/ to the CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/lib directory.
Report a bug

⁠12.4.5. Setting up Logout Redirection

The CAS server displays the CAS logout page with a link to return to the portal by default. To make the CAS server redirect to the portal page after a logout, modify CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/cas-servlet.xml to include the followServiceRedirects="true" parameter: 
​<bean id="logoutController"  class="org.jasig.cas.web.LogoutController"
​  p:centralAuthenticationService-ref="centralAuthenticationService"
​  p:logoutView="casLogoutView"
​  p:warnCookieGenerator-ref="warnCookieGenerator"
​  p:ticketGrantingTicketCookieGenerator-ref="ticketGrantingTicketCookieGenerator"
​  p:followServiceRedirects="true"/>
Report a bug

⁠12.4.6. Cookie Configuration for Central Authentication Service (CAS) Single Sign-on

Jasic CAS uses a cookie named CAS Ticket Granting Cookie (CASTGC) to control the authentication state within the browser session. The cookie contains a Ticket Granting Ticket (TGT), which preserves SSO authentication where more than one site is controlled by the same SSO profile.
Report a bug

⁠12.4.7. Portal Authentication using Central Authentication Service Ticket Granting Cookie (CASTGC)

Two portal servers are provisioned that use a single CAS server to manage authentication. The portals are named accounts and services.
When a user initially accesses the accounts portal, they provide their SSO credentials, and CAS authenticates them as a registered user. The user then switches to the services portal, and is authenticated when she clicks the Sign in link.
This behavior is correct given this example because the browser instance stores the browser authentication state using the CASTGC cookie. The CASTGC cookie in this instance creates new ticket for the services portal automatically based on the authentication state present for the accounts portal.
This behavior exists through a secured connection only (https connection). To benefit from authentication across two or more portals, one of the options below must be implemented. Choose the correct option based on the deployment environment:
Testing
Alter the CASTGC cookie to be insecure.
The cookie can be accessed through http (insecure) connections.
To configure this test behavior, open CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/spring-configuration/ticketGrantingTicketCookieGenerator.xml and switch the attribute cookieSecure to false. 
​<bean id="ticketGrantingTicketCookieGenerator"
​  p:cookieSecure="false"
​  p:cookieMaxAge="-1"
​  p:cookieName="CASTGC"
​  p:cookiePath="/cas" />
Production
Correctly implement the https protocol for all production servers that rely on CAS. This configuration is the recommended method for any production server, and ensures greater security for CAS connections. See the Jasig documentation about securing CAS https://wiki.jasig.org/display/CASUM/Securing+Your+New+CAS+Server for information and resources.
Report a bug

⁠12.4.8. Installing Apache Tomcat Server

Prerequisites:

Install and configure Apache Tomcat 7, which provides the host server for the CAS server.
⁠

Procedure 12.2. Configuring Apache Tomcat for CAS

  1. Visit http://tomcat.apache.org/download-70.cgi and download the Tomcat 7 binary distribution.
  2. Extract and install the binary on the server that is required to host CAS. This directory is now referred to as TOMCAT_HOME.
  3. Edit TOMCAT_HOME/conf/server.xml and change port 8080 to 8888 to avoid a conflict with the default portal listen port.

    Important

    If the Apache Tomcat server is installed on the same machine as the portal, ensure other listen ports common to both servers are changed to prevent configuration issues. For example, change the Tomcat admin port from 8005 to 8805, and the Tomcat AJP port from 8009 to 8809.
  4. Ensure all Apache Tomcat ports are open in the server firewall, and the service is enabled and running so the portal can communicate with Apache Tomcat on the same server.
Report a bug

⁠12.5. Modifying the Portal

Before building and deploying the Jasig CAS sever, configuration must be implemented on the portal to prepare it for CAS integration.
Report a bug

⁠12.5.1. Configuring Portal Single Sign-on

The main portal configuration file for SSO integration is JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/sso/security-sso-configuration.xml. All required SSO components such as agents and SSO interceptors are configured in this file.
In most cases, it will never be necessary to edit security-sso-configuration.xml directly when using the portal. The portal architecture allows users to override the base configuration described in this file using name/value pairs configured in one place: JPP_HOME/standalone/configuration/gatein/configuration.properties
The exception to this rule is where configuration present in security-sso-configuration.xml is fundamentally unsuitable for the production environment the server will be deployed to, or when additional underlying functionality is required (for example, another custom interceptor).
Report a bug

⁠12.5.2. Configuration properties for Portal Single Sign-on

To prepare the portal for CAS authentication, SSO filters and login modules need to be specified in global configuration files. The location of the CAS server, as configured in a locally-running Apache Tomcat server, must also be specified.
⁠

Procedure 12.3. Configuring SSO configuration.properties for CAS

  1. Open JPP_HOME/standalone/configuration/gatein/configuration.properties and locate the SSO section in the file.
  2. Make the following changes to the file to declare the correct login module, server and portal URLs, and the logout filter. 
    # SSO
gatein.sso.enabled=true
gatein.sso.callback.enabled=${gatein.sso.enabled}
gatein.sso.login.module.enabled=${gatein.sso.enabled}
gatein.sso.login.module.class=org.gatein.sso.agent.login.SSOLoginModule
gatein.sso.server.url=http://localhost:8888/cas
gatein.sso.portal.url=http://localhost:8080
gatein.sso.filter.logout.class=org.gatein.sso.agent.filter.CASLogoutFilter
gatein.sso.filter.logout.url=${gatein.sso.server.url}/logout
gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/login?service=${gatein.sso.portal.url}/@@portal.container.name@@/initiatessologin
gatein.sso.enabled
Specifies whether SSO integration is enabled on the portal. With this option set to "true" when a user clicks the Sign in link, the user is redirected to the /portal/sso/ URL rather than a standard Sign in dialog.
gatein.sso.callback.enabled
Specifies whether the REST callback authentication handler is enabled.
The handler is required if the CAS server must use the SSO Authentication plug-in to handle portal authentication. The callback handler is enabled by default. Set the parameter to false if the authentication plug-in on the CAS server side is not required.
gatein.sso.login.module.enabled
Specifies whether a pre-defined SSO login module declared in JPP_HOME/standalone/configuration/standalone.xml is used for authentication. When the property is set to true, the SSODelegateLoginModule delegates work to another login module, as specified using the gatein.sso.login.module.class property. SSODelegateLoginModule will also resend all its options to its delegate.
This parameter removes the need to manually change any login module configuration in the standalone.xml file, which simplifies platform configuration.
gatein.sso.login.module.class
Specifies the classname of the login module SSODelegateLoginModule will delegate to. This parameter will work only if gatein.sso.login.module.enabled is specified.
gatein.sso.server.url
Specifies the URL from which the CAS server is accessible.
gatein.sso.portal.url
Specifies the URL from which the portal is accessible.
gatein.sso.filter.logout.class
Specifies the class of the logout filter. In the example above org.gatein.sso.agent.filter.CASLogoutFilter is the correct choice because this filter is able to redirect to the CAS server and perform logout on the CAS side.
gatein.sso.filter.logout.url
Specifies the CAS server logout URL, which is used for redirection by the logout filter.
gatein.sso.filter.logout.enabled
Optional parameter, which specifies whether the logout interceptor is enabled. To disable logout on CAS side, set the parameter value to false. This causes both options gatein.sso.filter.logout.class and gatein.sso.filter.logout.url to be ignored.
When a user logs out of the portal, the CAS authentication ticket is still valid for other CAS authenticated sites.
gatein.sso.filter.login.sso.url
Specifies the CAS server login URL, which is used by LoginRedirectFilter for redirection to the CAS server login page.

Note

The string @@portal.container.name@@is dynamically replaced when the URL is interpreted by the platform's SSO Component. It is recommended that this string is used over manually specifying the name of the portal for future maintenance and ease of configuration changes.

See Also:

Report a bug

⁠12.6. Building and Deploying Central Authentication Service (CAS)

Jasig CAS uses Apache Maven to build the cas.war file. Follow the instructions to produce this file, and deploy it to the Apache Tomcat server.
⁠

Procedure 12.4. Building and Deploying CAS to Tomcat

  1. Install Maven by following the recommendations and links in the Building and Deploying section of the Jasig CAS user documentation.
  2. In a terminal, navigate to CAS_DIR/cas-server-webapp/, and run mvn clean install -Dmaven.test.skip=true.
  3. Copy CAS_DIR/cas-server-webapp/target/cas.war to TOMCAT_HOME/webapps.
  4. Tomcat should be running by default, if the process has been followed up to this step. Start the portal, and verify the server is running by opening http://localhost:8080/.
  5. Open http://localhost:8888/cas to verify the CAS server has correctly deployed to Tomcat. If the link does not open the CAS login page, restart Apache Tomcat and try again.
The CAS server is now deployed to Tomcat, and the portal will now redirect users to the CAS login page when they click on the Sign In link.
Report a bug