JBoss Community Archive (Read Only)

GateIn Portal 3.6

Central Authentication Service (CAS)

This Single Sign On plugin enables seamless integration between GateIn Portal and the CAS Single Sign On Framework. Details about CAS can be found here.

The integration consists of two parts:

How the integration works

Login workflow

The whole authentication process with CAS integration works like this:

  1. Non-authenticated user is on GateIn Portal page. He wants to authenticate and so he clicks Sign in link. Normally this will show GateIn Portal login dialog, but when SSO integration is enabled, it will redirect user to special marker URL like: http://localhost:8080/portal/sso

  2. There is special interceptor (Servlet filter) LoginRedirectFilter on GateIn Portal side, which is able to handle /portal/sso URL and it redirects user to CAS server page.

  3. So user is redirected to CAS login page http://localhost:8888/cas/login . He is asked to fill his credentials and authenticate on CAS server side .
    It's up to CAS administrator how he configure authentication on CAS side to prove user credentials. For example you can configure CAS to obtain credentials from some external DB or LDAP server. However GateIn Portal SSO component provides special authentication plugin, which can be deployed and configured on CAS server. This plugin is verifying user credentials by connect to existing GateIn Portal instance via back channel with usage of REST over HTTP protocol. In this case, GateIn Portal will serve Rest authentication callback request and it will verify user identity against GateIn Portal's own identity storage provided by portal OrganizationService (typically based on Picketlink IDM database) and send response to CAS server with the result.
    Please note that using of this Authentication plugin is not mandatory for integration with GateIn Portal. You can use whatever you want for authentication on CAS side (like external DB or LDAP) as already mentioned. But using of GateIn Portal SSO authentication plugin has one important advantage, that you need to have only single identity storage for storing users/groups/roles. So if you add new user via GateIn Portal UI, you are immediately able to authenticate this user with CAS server. More info about how to configure CAS to use Authentication plugin is in Authentication plugin setup.

  4. Once user is authenticated on CAS side, he is redirected back to GateIn Portal to URL like http://localhost:8080/portal/initiatelogin . There is another filter InitiateLoginFilter, which  intercepts /portal/initiatelogin URL. This filter will obtain CAS ticket attached in HTTP request inside parameter ticket and it delegates validation of this ticket to configured CASAgent component. CAS agent then validates ticket by sending validation request to CAS server via back channel. Response from CAS contains username of the user who authenticated on CAS side in step 3.

  5. After SSO validation, InitiateLoginFilter redirects user to portal login URL like http://localhost:8080/portal/login, which performs JAAS authentication. SSOLoginModule will recognize if user has been successfully validated by CASAgent and if it's the case, it will obtain data about user (groups, memberships) from OrganizationService and encapsulate them into Identity object. Another Login module JBossAS7LoginModule (or TomcatLoginModule) is able to finish authentication by establish JAAS Subject and save Identity object to IdentityRegistry (See Authentication and Authorization intro#Login modules for more details).
    So you can notice that CAS is used only for authenticating user, but informations about roles and group memberships are still obtained from GateIn Portal OrganizationService (Picketlink IDM database)

  6. After successful JAAS authentication is user redirected to GateIn Portal and he is properly authenticated and authorized now.

Logout workflow

  1. Authenticated user clicks to Sign out link.

  2. There is interceptor CASLogoutFilter, which recognize logout request and it redirects user to CAS logout page http://localhost:8888/cas/logout

  3. CAS server will logout user on it's side and invalidate CAS cookie CASTGC . Then it redirects user back to GateIn Portal (Proper redirection to portal requires another change in CAS server configuration as mentioned in Logout redirection setup).

  4. Request to GateIn Portal will finish logout process on it's side and user will be redirected to GateIn Portal anonymous page. So note that if CASLogoutFilter is enabled, user is logged out from both GateIn Portal and CAS server.

CAS server

For simplification purpose, we assume that CAS 3.5 will be deployed on Tomcat 7 server, which will listen on localhost:8888 . GateIn Portal will be deployed on JBoss AS 7, which will listen on localhost:8080 .

First, set up the server to authenticate against the portal via REST callback.

Obtaining CAS

CAS can be downloaded from http://www.jasig.org/cas/download. The tested version which should work with these instructions is CAS 3.5. However, other versions can also work.

Extract the downloaded file into a suitable location. This location will be referred to as CAS_HOME in the following instructions.

Modifying the CAS server

To configure the web archive as desired, the simplest way is to make the necessary changes directly in the CAS codebase.

Important

To complete these instructions, and perform the final build step, you will need the Apache Maven 3. You can get it here.

Authentication plugin setup

As already mentioned, this is not mandatory and is needed only if you want setup CAS to make secure authentication callbacks to a RESTful service installed on the remote GateIn Portal

In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the cas.war/WEB-INF/deployerConfigContext.xml file.

  1. Open CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml.

  2. Replace 

    <!--
	| 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" />

    With the following that is also available in GATEIN_SSO_HOME/cas/plugin/WEB-INF/deployerConfigContext.xml (Make sure you set the host, port and context with the values corresponding to your portal). GATEIN_SSO_HOME refers to directory with GateIn Portal SSO artifacts as mentioned in Single-Sign-On (SSO) . 

    <!--
	| 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.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>

  3. Copy all jars from GATEIN_SSO_HOME/cas/plugin/WEB-INF/lib/ into the CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/lib created directory.

Logout redirection setup

By default on logout the CAS server will display the CAS logout page with a link to return to the portal. To make the CAS server redirect to the portal page after a logout, modify CAS_HOME/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"/>

CAS SSO cookie configuration

CAS server is using special cookie CASTGC, which is useful for SSO scenarios with more Service applications. For example, you have single CAS server and 2 GateIn Portal servers configured to use it (let's mark those  GateIn Portal instances as accounts and services). So if you login against CAS server with accounts GateIn Portal instance, you don't need to reauthenticate again when you access CAS with services GateIn Portal instance. You will be automatically authenticated when click Sign in on services instance. This is real SSO and it works thanks to CASTGC cookie, which automatically creates new ticket for services instance if it recognize that user is already authenticated.

Thing is that CASTGC cookie is secured by default (aka. available only from https connections). So by default the "real" SSO doesn't work and you need to reauthenticate when accessing CAS from your services instance. So if you really want to support this scenario with more nodes, you have 2 possibilities:

  • Use https protocol to access your CAS server. This will ensure that secure CASTGC cookie can be viewable by browser. This is recommended approach for production environments. See https://wiki.jasig.org/display/CASUM/Securing+Your+New+CAS+Server for more details.

  • Easier workaround (but not recommended in production environment) is to switch CASTGC cookie to be non-secure (ie. cookie won't need secure access through https but can be accessed from http as well). To achieve this you need to configure in CAS side in file  CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/spring-configuration/ticketGrantingTicketCookieGenerator.xml and switch attribute cookieSecure to false. Configuration of cookie generator in this file should look like this: 

    <bean id="ticketGrantingTicketCookieGenerator"
  p:cookieSecure="false"
  p:cookieMaxAge="-1"
  p:cookieName="CASTGC"
  p:cookiePath="/cas" />

SSO server setup

  1. Get an installation of Tomcat 7 from http://tomcat.apache.org/download-70.cgi and extract it into a suitable location (which will be called TOMCAT_HOME for these instructions).
    Change the default port to avoid a conflict with the default GateIn Portal (for testing purposes). Edit TOMCAT_HOME/conf/server.xml and replace the 8080 port with 8888.

    Important

    If GateIn Portal is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 to avoid port conflicts. They can be changed to any free port. For example, you can change admin port from 8005 to 8805, and AJP port from 8009 to 8809.

  2. Go to CAS_HOME/cas-server-webapp and execute the command: 

    mvn clean install -Dmaven.test.skip=true

  3. Copy CAS_HOME/cas-server-webapp/target/cas.war into TOMCAT_HOME/webapps.

  4. Tomcat should start and be accessible at http://localhost:8888/cas.

    Important

    The login will not be available at this stage if you configure authentication against Authentication plugin as  GateIn Portal is not started yet.

    images/author/download/attachments/62587020/cas.png

Setup the portal

Assuming you have GateIn Portal bundled with JBoss AS7, all you need to do on portal side is to configure couple of configuration properties in file GATEIN_HOME/standalone/configuration/gatein/configuration.properties . Find SSO section in this file and change/add properties so that it looks like this: 

# 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

In previous versions of GateIn Portal, there were much more changes needed in various configuration file but it's not the case anymore. Now all JARS are available in AS7 module org.gatein.sso so you don't need to manually add any JAR files. If you are interested in technical details about single properties and configuration, you can see next section with configuration properties details.

Configuration properties details

  • gatein.sso.enabled - This option will generally enable SSO integration and informs GateIn Portal about that. So for example now when you click to Sign in link, you won't see login dialog, but will be redirected to /portal/sso URL

  • gatein.sso.callback.enabled - This will enable REST callback authentication handler, which is needed if you want CAS server to use SSO Authentication plugin for CAS own authentication. See Login workflow point 3 for details. By default, callback handler is enabled if option gatein.sso.enabled is true. You can switch it to false if you don't want to use Authentication Plugin on CAS server side.

  • gatein.sso.login.module.enabled - There is special login module configured for gatein-domain in GATEIN_HOME/standalone/configuration/standalone.xml called SSODelegateLoginModule . If SSO is disabled, this SSODelegateLoginModule is simply ignored during authentication process. But if SSO is enabled by this property, it delegates the work to another login module configured via next option gatein.sso.login.module.class . SSODelegateLoginModule will also resend all it's options to it's delegate. In case of CAS server, we will use org.gatein.sso.agent.login.SSOLoginModule as delegate. The point of this architecture is, that people don't need to manually change any login module configurations in standalone.xml file.

  • gatein.sso.login.module.class - See previous paragraph

The main GateIn Portal configuration file for SSO integration is GATEIN_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/sso/security-sso-configuration.xml . All needed SSO components like agents and SSO interceptors (former servlet filters) are configured in this file. The idea is that you never need to manually edit this file as most of the options are configurable via configuration.properties . But in case that something is really not suitable for your use-case or you need to add another custom interceptor or something else, you can manually edit it here. All the additional configuration properties are used especially for substitute values in this security-sso-configuration.xml file.

  • gatein.sso.server.url - Here you need to configure where your CAS server is deployed

  • gatein.sso.portal.url - Here is URL for access to your GateIn Portal server (actually server you are just configuring)

  • gatein.sso.filter.logout.class - Class of logout filter, which needs to be set to org.gatein.sso.agent.filter.CASLogoutFilter . This filter is able to redirect to CAS server and performs logout on CAS side. 

  • gatein.sso.filter.logout.url - CAS server logout URL, which will be used for redirection by logout filter

    If you want to disable logout on CAS side, you can simply disable this logout interceptor by adding option gatein.sso.filter.logout.enabled with value false. This will cause that click to Sign out on portal side will logout user from GateIn Portal but not from CAS server. In this case both options gatein.sso.filter.logout.class and gatein.sso.filter.logout.url will be ignored.

  • gatein.sso.filter.login.sso.url - CAS server login URL, which will be used by LoginRedirectFilter for redirection to CAS server login page.

    The string @@portal.container.name@@ will be dynamically replaced by correct name of portal container, where it will be executed. GateIn Portal SSO component will do it. So in configuration, you should really use string @@portal.container.name@@ instead of some hardcoded portal container name (like portal or sample-portal)

Once these changes have been made, all links to the user authentication pages will redirect to the CAS centralized authentication form. And on CAS you will be able to authenticate with portal credentials (like john/gtn) thanks to Authentication plugin.

Setup with portal on Tomcat

If you have GateIn Portal on Tomcat7 and you want to use CAS for authentication, you can change file GATEIN_HOME/gatein/conf/configuration.properties and configure them exactly same like for GateIn Portal on JBoss AS7. There is only one additional thing you need to do:

In file GATEIN_HOME/conf/server.xml you need to add special ServletAccessValve under Host element: 

<Host name="localhost" appBase="webapps"
  unpackWARs="true" autoDeploy="true">

  <Valve className="org.gatein.sso.agent.tomcat.ServletAccessValve" />

  <!-- SingleSignOn valve, share authentication between web applications
  ...
JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-10 12:57:19 UTC, last content change 2013-04-22 15:47:24 UTC.