- 1 How the integration works
- 2 CAS server
- 2.1 Obtaining CAS
- 2.2 Modifying the CAS server
- 3 Setup the portal
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:
- The first consists of installing or configuring a CAS server.
- The second consists of setting up the portal to use the CAS server.
The whole authentication process with CAS integration works like this:
- 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
- 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.
- 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.
- 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.
- 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)
- After successful JAAS authentication is user redirected to GateIn Portal and he is properly authenticated and authorized now.
- Authenticated user clicks to Sign out link.
- There is interceptor CASLogoutFilter, which recognize logout request and it redirects user to CAS logout page http://localhost:8888/cas/logout
- 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).
- 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.
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.
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.
To configure the web archive as desired, the simplest way is to make the necessary changes directly in the CAS codebase.
To complete these instructions, and perform the final build step, you will need the Apache Maven 3. You can get it here.
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.
- Open CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml.
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) .
- 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.
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:
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:
- 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.
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.
- Go to CAS_HOME/cas-server-webapp and execute the command:
- Copy CAS_HOME/cas-server-webapp/target/cas.war into TOMCAT_HOME/webapps.
- Tomcat should start and be accessible at http://localhost:8888/cas.
The login will not be available at this stage if you configure authentication against Authentication plugin as GateIn Portal is not started yet.
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:
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.
- 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.
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: