OpenAM - GateIn Portal 3.8

Setting up this integration involves two steps. The first step is to install or configure an OpenAM server, and the second is to set up the portal to use the OpenAM server. In this sample setup, we will assume again that GateIn Portal will be running on JBoss AS7 and on localhost:8080 and JOSSO server will be running on Tomcat on localhost:8888 .

Login and logout workflow

Login workflow for OpenAM is quite similar like for CAS, so you can look to Central Authentication Service (CAS)#Login workflow for more details. Basically after click to Sign in on GateIn Portal page is user redirected to OpenAM login screen where he provides his credentials. Then he is redirected back to GateIn Portal. InitiateLoginFilter will then delegate validation of OpenAM ticket, which is in cookie iPlanetDirectoryPro to OpenSSOAgent component, which performs validation of ticket with OpenAM server via back channel. Actually agent is using OpenAM REST API to verify ticket. After successful validation is user identity successfully established and user is logged in GateIn Portal.

For logout part, there is OpenSSOLogoutFilter, which performs logout on both GateIn Portal and OpenAM server (similarly like for CAS).

For OpenAM authentication part, we again support authentication plugin, which is able to send REST request to GateIn Portal and then obtain response from portal and authenticate user on OpenAM side based on it.

OpenAM server setup

This section details setting up of OpenAM server to authenticate against the GateIn Portal with usage of REST callback. So similarly like for CAS and JOSSO, we support Authentication plugin, which can be set on OpenAM to authenticate against portal. But note again that it's not mandatory to use this callback, you can use whatever you want for authentication on OpenAM side.

In this example, the OpenAM server will be installed on Tomcat.

Obtaining OpenAM

For GateIn Portal integration, we support and test OpenAM of versions 9.5 or 10.0. However other versions can still work (also OpenAM predecessor OpenSSO can still work even if we stop to officially support it).

Once downloaded, extract the package into a suitable location. This location will be referred to as OPENAM_HOME in this example.

Modifying the OpenAM server

The first step is to deploy OpenAM to Tomcat 7 server and properly configure it. Recommended (but not mandatory) step is to add the GateIn Portal SSO Authentication Plugin. The plugin makes secure authentication callbacks to a RESTful service installed on the remote GateIn Portal server to authenticate a user. In these instructions we will setup it.

Obtain a copy of Tomcat 7 and extract it into a suitable location (this location will be referred to as TOMCAT_HOME in this example).
Deploy OpenAM to tomcat by copying OPENAM_HOME/opensso/deployable-war/opensso.war to TOMCAT_HOME/webapps .

The name of WAR file in ZIP distribution is still opensso.war even if we have OpenAM, which is defacto OpenSSO successor. Also the context of OpenAM web application is still /opensso
Change the default port to avoid a conflict with the default GateIn Portal (for testing purposes) by editing TOMCAT_HOME/conf/server.xml and replacing 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 the admin port from 8005 to 8805, and AJP port from 8009 to 8809.

Authentication plugin setup

Copy content of GATEIN_SSO_HOME/opensso/plugin to TOMCAT_HOME/webapps/opensso (GATEIN_SSO_HOME points to location with extracted GateIn Portal SSO packaging as described in Single-Sign-On (SSO) )
This will add:
- TOMCAT_HOME/webapps/opensso/config/auth/default/AuthenticationPlugin.xml file, which looks like this:
```
<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE ModuleProperties PUBLIC "=//iPlanet//Authentication Module Properties XML Interface 1.0 DTD//EN"
          "jar://com/sun/identity/authentication/Auth_Module_Properties.dtd">

<ModuleProperties moduleName="AuthenticationPlugin" version="1.0" >
  <Callbacks length="2" order="1" timeout="60"
             header="GateIn OpenAM Login" >
    <NameCallback>
      <Prompt>
        Username
      </Prompt>
    </NameCallback>
    <PasswordCallback echoPassword="false" >
      <Prompt>
        Password
      </Prompt>
    </PasswordCallback>
  </Callbacks>
</ModuleProperties>
```
- Some JARS like sso-opensso-plugin-<VERSION>.jar and commons-httpclient-<VERSION>.jar and few others to directory TOMCAT_HOME/webapps/opensso/WEB-INF/lib .
- File TOMCAT_HOME/webapps/opensso/WEB-INF/classes/gatein.properties. You may need to configure the host, port, protocol or other properties in this file according to your GateIn Portal location. This will be used by Authentication plugin for REST connection to portal over HTTP protocol.
Start Tomcat to be able to access http://localhost:8888/opensso.

Configure realm in OpenAM UI

Direct your browser to http://localhost:8888/opensso.
Create the default configuration.
Login as amadmin and then go to Configuration -> Authentication. Next, select the Core link, and add new value and fill in the org.gatein.sso.opensso.plugin.AuthenticationPlugin class name and finally click "Save". This step is important for setup of GateIn Portal SSO AuthenticationPlugin to be available among other OpenAM authentication modules.
Go to the Access control tab and create a new realm called gatein.
Go to the gatein realm, and click on the Authentication tab. At the bottom in the Authentication chaining section, click on ldapService. Here change the selection from Datastore, which is the default module in the authentication chain, to AuthenticationPlugin. This enables authentication of the gatein realm by using GateIn Portal REST service instead of the OpenAM LDAP server.
When you are on Authentication tab of gatein realm, click to button All Core Settings . Then change UserProfile from Required to Dynamic. This step is needed because GateIn Portal users are not in OpenAM Datastore (LDAP server), so their profiles can not be obtained if "Required" is active. By using "Dynamic", all new users are automatically created in OpenAM datastore after successful authentication.
Increase the user privileges to allow REST access. Go to Access control -> Top level realm -> Privileges -> All authenticated users, and check the checkboxes:

Read and write access only for policy properties
Read and write access to all realm and policy properties

Repeat previous step with increasing privileges for the gatein realm as well.
images/author/download/attachments/78709340/openam-conf-policies.png

Setup the OpenAM client

We assume that GateIn Portal, which will act as OpenAM client, will be running on JBoss AS7. So you need 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 to look 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/opensso
gatein.sso.openam.realm=gatein
gatein.sso.portal.url=http://localhost:8080
gatein.sso.filter.logout.class=org.gatein.sso.agent.filter.OpenSSOLogoutFilter
gatein.sso.filter.logout.url=${gatein.sso.server.url}/UI/Logout
gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/UI/Login?realm=${gatein.sso.openam.realm}&goto=${gatein.sso.portal.url}/@@portal.container.name@@/initiatessologin

OpenAM 12.0 has a bug on the logout procedure via their new UI (called XUI) which prevents the correct redirection. A possible workaround is to disable the newest UI (XUI) and use the classic UI. To do so, open the OpenAM administration console, access "Configuration", then "Core" and uncheck the option "XUI interface".
See https://bugster.forgerock.org/jira/browse/OPENAM-5467

Most of the properties were already described in Central Authentication Service (CAS)#Configuration properties details . For OpenAM some of the properties are different, especially URL for redirection to login/logout to OpenAM server and Logout filter class is now org.gatein.sso.agent.filter.OpenSSOLogoutFilter. Very important property is gatein.sso.server.url, which points to location of OpenAM server. Also gatein.sso.portal.url will need to be changed if you expect GateIn Portal to be accessed on different URL than http://localhost:8080 . Property gatein.sso.openam.realm points to realm, which needs to be available in OpenAM server. We assume that name of the realm is gatein as configured in previous section Configure realm in OpenAM UI .

From now on, all links redirecting to the user authentication pages will redirect to the OpenAM centralized authentication form. On OpenAM side, you can login with GateIn Portal credentials (for example john/gtn) to gatein realm if you properly configured Authentication plugin.
images/author/download/attachments/78709340/openam.png

Setup with portal on Tomcat

If you have GateIn Portal on Tomcat 7 and you want to configure it for SSO against OpenAM, you additionally need to add ServletAccessValve into server.xml similarly like for CAS setup. See Central Authentication Service (CAS)#Setup with portal on Tomcat for more details.

Cross-domain authentication with OpenAM

The authentication scenario described in previous parts assumes that GateIn Portal and OpenAM are deployed on the same server or in same DNS domain (like OpenAM on opensso.shareddomain.com and GateIn Portal on portal.shareddomain.com).

After successful authentication in OpenAM console, OpenAM will add special cookie iPlanetDirectoryPro for DNS domain shareddomain.com and then it redirects to portal agent. Portal OpenSSOAgent can read SSO token from this cookie because cookie is in same DNS domain, so it can perform validation of token. In other words, exchange of secret token between OpenAM and GateIn Portal is done through this shared cookie.

This approach cannot work in situations, when GateIn Portal server and OpenAM server are in different domains and cannot share cookie. For this scenario, OpenAM provides special servlet CDCServlet. Authenticated user can send request to this servlet and servlet will send him encoded SAML message with SSO token and other informations. Portal agent is then able to parse and validate this message, obtain SSO token and establish iPlanetDirectoryPro cookie for server where portal is deployed. Once OpenAM agent on portal side has token, it can perform other validations of this token and successfully finish authentication of user.

You can follow this link for more technical information about CDCServlet.

Cross-domain authentication configuration

Assume that your OpenAM server is deployed on host opensso.mydomain.com and GateIn Portal on portal.yourdomain.com. If you are on single machine, you can simply simulate this scenario by using virtual hosts. On linux you can edit the /etc/hosts file and add records similar to those (change according to IP addresses in your environment):
```
opensso.mydomain.com 192.168.2.7
portal.yourdomain.com 10.11.12.13
```

SSO configuration in file configuration.properties on GateIn Portal side needs to look 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://opensso.mydomain.com:8888/opensso
gatein.sso.openam.realm=gatein
gatein.sso.portal.url=http://portal.yourdomain.com:8080
gatein.sso.filter.logout.class=org.gatein.sso.agent.filter.OpenSSOLogoutFilter
gatein.sso.filter.logout.url=${gatein.sso.server.url}/UI/Logout
gatein.sso.filter.login.enabled=false
gatein.sso.filter.login.openamcdc.enabled=true
gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/cdcservlet

The important part are last 3 properties (We needs to redirect to OpenAM cdcservlet, so we are using modified version of LoginRedirectFilter. That's why gatein.sso.filter.login.openamcdc.enabled is changed to true and gatein.sso.filter.login.enabled is false. Also gatein.sso.filter.login.sso.url now points to URL of OpenAM cdcservlet)

On OpenAM side, it is mandatory to create agent for GateIn Portal server. This agent is required by CDCServlet to work properly. You can create agent in OpenAM UI by performing these steps:
- Go to http://opensso.mydomain.com:8888/opensso and login as amadmin.
- Go to Access Control -> Realm "gatein" -> Agents -> Web.
- Create new web agent through the wizard. You can use these properties:
- Name: GateInAgent
- Password: Whatever you want.
- Configuration: Centralized
- Server URL: http://opensso.mydomain.com:8888/opensso
- Agent URL: http://portal.yourdomain.com:8080
  If you have more portal servers on different hosts, you may want to create agent for each of them. Please look at OpenAM administration guide for more details.