Procedure 14.1. Setting up OpenAM Server

1. Deploy the OpenAM server.
2. Add the authentication plugin.
3. Configure a realm in OpenAM user interface.

Procedure 14.2. Deploying the OpenAM Server

1. Obtain a copy of Tomcat 7 and extract it into a suitable location. This location will be referred to as TOMCAT_HOME further in the text.
2. Deploy OpenAM to Tomcat by copying the OPENAM_HOME/opensso/deployable-war/opensso.war archive to the TOMCAT_HOME/webapps/ directory.

   Note

   The name of the WAR file is still opensso.war, even if it contains OpenAM, which is the successor of OpenSSO. The context of the OpenAM web application has also kept the name /opensso.
3. Change the default Tomcat port to avoid conflict with the default portal port. For the purpose of this example, change it to 8888 by editing the TOMCAT_HOME/conf/server.xml configuration file and replacing the 8080 port number with 8888.
4. If the portal is running on the same machine as Tomcat, other Tomcat port numbers also need to be changed to avoid conflicts. These port numbers can be changed to any unassigned port numbers available on the machine. For example, change the admin port from 8005 to 8805 and the AJP port from 8009 to 8809 if the latter are not assigned.

Procedure 14.3. Adding the Authentication Plug-in

1. Copy the contents of the JPP_DIST/gatein-sso/opensso/plug-in/ directory to TOMCAT_HOME/webapps/opensso/. This will add:
   • the AuthenticationPlugin.xml file to the TOMCAT_HOME/webapps/opensso/config/auth/default/ directory. The file contains the following configuration:
     ⁠

     Example 14.1. AuthenticationPlugin.xml Example Content

     ​
     ​<?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>
     

   • the sso-opensso-plugin-<VERSION>.jar, sso-common-plugin-<VERSION>.jar and commons-httpclient-<VERSION>.jar archives to the TOMCAT_HOME/webapps/opensso/WEB-INF/lib directory.
   • the gatein.properties file to the TOMCAT_HOME/webapps/opensso/WEB-INF/classes/ directory. If necessary, change the values specified in this file to match the configuration of the portal instance. The values are used by the authentication plug-in to establish the REST connection to the portal.
2. Start Tomcat and verify that the OpenAM user interface at http://localhost:8888/opensso is accessible.

Procedure 14.4. Configuring a Realm in OpenAM User Interface

1. Open http://localhost:8888/opensso.
2. Create the default configuration.
3. Login as amadmin and navigate to Configuration → Authentication.
4. Select the Core link, add a new value containing the org.gatein.sso.opensso.plugin.AuthenticationPlugin class name and click Save. This step is important for the portal SSO Authentication Plug-in to be available among other OpenAM authentication modules.
5. Go to the Access control tab and create a new realm called gatein.
6. Go to the gatein realm and click the Authentication tab. In the Authentication chaining section at the bottom of the tab, click ldapService. Here, change the selection from Datastore, which is the default module in the authentication chain, to AuthenticationPlugin. This ensures that authentication of the gatein realm will be performed using the portal REST service instead of the OpenAM LDAP server.
7. Still on the Authentication tab of the gatein realm, click the All Core Settings button. When the settings are displayed, change the UserProfile value from Required to Dynamic. This is needed because portal users are not initially present in the OpenAM LDAP server data store. The Dynamic value ensures that all users are automatically added to the data store after their first successful authentication.
8. Go to Access control → Top level realm → Privileges → All authenticated users and mark the following check boxes:
   • Read and write access only for policy properties
   • Read and write access to all realm and policy properties
   Adding these privileges allows REST access to the OpenAM server.
9. Repeat the previous step to increase the privileges also for the gatein realm.

Procedure 14.5. Cross-domain Authentication Configuration

opensso.mydomain.com 192.168.2.7
portal.yourdomain.com 10.11.12.13

1. On the portal side, single sign-on configuration in the configuration.properties file must be specified as follows:

   # 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
   

   As we need to redirect requests to the CDCServlet, the gatein.sso.filter.login.sso.url property points to the URL of the servlet. It is also necessary to use a modified version of the LoginRedirectFilter interceptor. That is why the gatein.sso.filter.login.openamcdc.enabled value is changed to true and the gatein.sso.filter.login.enabled value is now set to false.
2. Access the OpenAM user interface at http://opensso.mydomain.com:8888/opensso and log in as amadmin.
3. Navigate to Access Control → "gatein" realm → Agents → Web.
4. Create a new web agent through the wizard using the following properties:
   • Name: GateInAgent
   • Password: A password of your choice.
   • Configuration: Centralized
   • Server URL: http://opensso.mydomain.com:8888/opensso
   • Agent URL: http://portal.yourdomain.com:8080
   Creating this agent is required for the CDCServlet to work properly. If you have more portal servers on different hosts, you may want to create an agent for each of them. See the OpenAM Administration Guide available from http://openam.forgerock.org/doc/admin-guide/index.html for more details.