4.8.3.1. OpenAM server setup

If you store users in eXo Platform, you need to configure OpenAM to call back the eXo Platform service to validate a login. In this case (called "callback"), eXo provides the Authentication plugin (org.gatein.sso.opensso.plugin.AuthenticationPlugin - that is similar to CAS and JOSSO) that can be set on the OpenAM server. This plugin makes secure authentication callbacks to a RESTful service installed on the remote eXo Platform server to authenticate a user. Meanwhile, if you store users in another external datasource rather than eXo Platform (called non-callback), you will not need to install the Authentication plugin.

On the OpenAM server side, the following packages are required:

$GATEIN_SSO_HOME: The GateIn SSO package as mentioned in the Prerequisites of the SSO guideline. This is not needed in case of non-callback.
$OPENAM_HOME: The OpenAM package that you may purchase from Forgerock. For eXo Platform integration, eXo supports and tests the WAR distribution of OpenAM 10. However, the integration can still work with all versions. Once downloaded, extract the package to a location named $OPENAM_HOME.
$OPENAM_TOMCAT_HOME: A Servlet container on which OpenAM server will be deployed. In this tutorial, it is a Tomcat 7 package that you will download and extract to $OPENAM_TOMCAT_HOME in next steps.

Deploying OpenAM

The first procedure is the same for both callback and non-callback cases.

Obtain a copy of Tomcat 7 package and extract it into the location named $OPENAM_TOMCAT_HOME.
Deploy OpenAM to Tomcat by copying opensso.war (that is already extracted in $OPENAM_HOME) to $OPENAM_TOMCAT_HOME/webapps.
Note
The war file name is opensso.war that is the same to OpenSSO. Also, the web context is still /opensso, but it may differ if you use a snapshot of OpenAM.
Change the default port to avoid a conflict with the default eXo Platform (for testing purposes) by replacing the 8080 port with 8888 in $OPENAM_TOMCAT_HOME/conf/server.xml.
Note
If eXo Platform is running on the same machine as Tomcat, another ports need to be changed 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 the AJP port from 8009 to 8809.
Start the OpenAM Tomcat server ($OPENAM_TOMCAT_HOME\bin\startup.bat for Windows, or $OPENAM_TOMCAT_HOME/bin/startup.sh for Linux/OS X).

After deploying OpenAM, you need to properly configure the OpenAM server. The configuration will be different between callback or non-callback cases. In particular:

If you store users in eXo Platform, see Configuring the OpenAM server for callback case.
If you store users in another external datasource (such as default OpenAM DataStore, or LDAP), see Configuring the OpenAM server for non-callback case.

Configuring the OpenAM server for callback case

Step 1. Setting up the Authentication plugin

Copy and merge content of $GATEIN_SSO_HOME/opensso/plugin into $OPENAM_TOMCAT_HOME/webapps/opensso.
Check $OPENAM_TOMCAT_HOME/webapps/opensso/WEB-INF/classes/gatein.properties to ensure the correct information about your portal is already given as below:
```
host=localhost
port=8080
context=portal
protocol=http
httpMethod=POST
```

Step 2. Configuring realm in OpenAM UI

Start OpenAM Tomcat server, then browse http://localhost:8888/opensso. You will be redirected to the Configuration Options page like below.
Click the Create Default Configuration link. You will be auto-logged as a default user - amAdmin.
Enter passwords for Default User and Default Policy Agent, then click the Create Configuration button. Remember that these 2 passwords must be different.
You need to wait for some minutes when the OPENAM configuration is in progress. If the configuration is successful, you will receive a message stating "Configuration Complete!".
Click the Proceed to Login link.
Enter the username (amAdmin) and password created previously in the Sign in to OpenAM form, then click the Log In button. You will be redirected to the OpenAM Administration page.
Select Configuration tab → Authentication subtab → Core link.
Enter org.gatein.sso.opensso.plugin.AuthenticationPlugin into the New Value field, then click Add and Save.
Note
This step is important for setup of GateIn Portal SSO AuthenticationPlugin to be available among other OpenAM authentication modules.
Click Back to Service Configuration, then select the Access Control tab, and click the New button to create a new realm, named "gatein".
Enter gatein into the Name field, then click OK.
Go to the "gatein" realm and select the Authentication tab. At the bottom of the Authentication Chaining section, click ldapService. Here, change the selection from Datastore, which is the default module in the authentication chain, to AuthenticationPlugin, then click Save.
This enables the authentication of "gatein" realm by using the eXo Platform REST service instead of the default DataStore.
Click Back to Authentication, then Back to Access Control. Here, select Configuration tab → Authentication subtab → Core → Realm Attributes → User Profile. In the User Profile form, change Required to Dynamic, then click Save.
Note
This step is needed because eXo Platform users are not in the OpenAM Datastore (LDAP server), so their profiles cannot be obtained if Required is active. By using Dynamic, all new users are automatically created in the OpenAM datastore after successful authentication.
Click Back to Service Configuration, then go to Access Control tab → Top Level Realm → Privileges tab → All Authenticated Users. Here, increase the user privileges to allow the REST access by ticking the two checkboxes:
- Read and write access only for policy properties
- Read and write access to all realm and policy properties
Click Save → Back to Privilege(s) → Back to Access Control to come back to the Realms window.
Select gatein, then go to Privileges tab to increase privileges for gatein realm as well, and click Save.

Now you can move to the next section to configure the eXo Platform server.

Configuring the OpenAM server for non-callback case

If you store users in an external datasource, configuring the OpenAM server is quite simple. You only need to create a new realm in OpenAM UI named "gatein". Besides, for testing purpose, the following procedure includes steps of creating a user that is stored into the default DataStore of OpenAM.

Start OpenAM Tomcat server, then browse http://localhost:8888/opensso. You will be redirected to the Configuration Options page.
Click the Create Default Configuration link. You will be auto-logged as a default user - amAdmin.
Enter passwords for Default User and Default Policy Agent, then click the Create Configuration button. Remember that these 2 passwords must be different.
You need to wait for some minutes when the OPENAM configuration is in progress. If the configuration is successful, you will receive a message stating "Configuration Complete!".
Click the Proceed to Login link.
Enter the username (amAdmin) and password created previously in the Sign in to OpenAM form, then click the Log In button. You will be redirected to the OpenAM Administration page.
Select the Access Control tab, then click the New button to create a new realm, named "gatein".
Enter gatein into the Name field, then click OK.
Come back to the Access Control tab, then click the "gatein" realm.
Create users for the "gatein" realm by selecting Subjects tab, then clicking New.
Enter information for the user (ID = "root" and password = "12345678", for example) in the New User form, then click OK to finish.
Note
To make the user stored in an external datasource be able to access eXo Platform resources, ensure that the user is already registered in eXo Platform also. To make convenient for login and access to eXo Platform later (for testing purpose), the user identifier (ID in this example) created in the external datasource should be one username existing in eXo Platform.

Now you can move to the next section to configure the eXo Platform server.

4.8.3.1. OpenAM server setup

Note

Note

Note

Note

Note