This tutorial walks you through an OpenAM integration with OpenAM's password capture and replay feature. This feature of OpenAM is typically used to integrate with Outlook Web Access or Sharepoint by capturing the password during OpenAM authentication, encrypting it, adding to the session, which is later decrypted and used for Basic Authentication to OWA or Sharepoint. This tutorial shows how you can configure OpenIG to use the user name and password from the OpenAM Authentication to log the user into WordPress. This is also how you would achieve OWA or Sharepoint integration.
The figure below illustrates the flow of requests for a user logging into OpenAM and then being logged into WordPress with the user name and password from the OpenAM login session.
User authenticates to OpenAM establishing a session, OpenAM is configured to capture the password, encrypt it, and then store it in the user's session.
User browses to a WordPress page requiring authentication.
OpenAM Agent intercepts the request, validates the user session, and populates HTTP headers with the user name and encrypted password from the session.
Agent passes the original request with populated headers to OpenIG.
OpenIG inspects the request, does not find a match for the WordPress login page, so forwards the request on.
WordPress finds no application session and redirects to its login page.
OpenIG intercepts, sees the login page, creates the login form with the user name and decrypted password from the headers inserted by the Agent.
WordPress validates the login form, returns an application session and the user's home page.
WordPress home page returned to the user.
OpenAM is installed on
http://www.idp.com:8888/openam. WordPress hosted on the
ForgeRock demo site at http://demo.forgerock.com:8080/wordpress, populated with a sample
user george with password costanza.
OpenIG is deployed on an instance of Tomcat protected by an OpenAM J2EE
agent. The J2EE agent is configured for cross domain SSO, and to add the user
name and replay password headers to the HTTP requests.
This section assumes you are familiar with the components involved.
Install and configure OpenAM on
http://www.idp.com:8888/openam with the default
configuration. You can install OpenAM with your configuration, but
be sure to substitute in the tutorial accordingly.
Create a sample user with user name george
and password constanza.
To test, startup OpenAM and make sure you can login with the
user name george and password
constanza.
Create the J2EE agent profile with the following settings:
Server URL http://www.idp.com:8888/openam
Agent URL http://demo.forgerock.com:8080/agentapp
Under Global settings change the Agent filter mode from ALL to SSO_ONLY
Under Application > Session Attributes Processing change the Session Attribute Fetch Mode from none to HTTP_Header
Under Application > Session Attributes Processing > Session Attribute Mappings add UserToken=username and sunIdentityUserPassword=password
Under SSO > Cross Domain SSO select the Enabled checkbox. If you have installed OpenAM in the forgerock.com domain you do not need to enable cross domain SSO.
In the OpenAM console under Access Control > Realm > Authentication click "All Core Settings" and add com.sun.identity.authentication.spi.ReplayPasswd to the Authentication Post Processing Classes.
Run java -classpath amserver.jar:opensso-sharedlib.jar com.sun.identity.common.DESGenKey to generate a shared key for the OpenAM Authentication plugin and OpenIG. As an example, if you have OpenAM installed under $HOME on Tomcat you would run the command java -classpath $HOME/tomcat7/webapps/openam/WEB-INF/lib/amserver.jar:$HOME/tomcat7/webapps/openam/WEB-INF/lib/opensso-sharedlib.jar com.sun.identity.common.DESGenKey.
In the OpenAM console under Configuration > Servers and Sites click on your server name, go to Advanced and add com.sun.am.replaypasswd.key with the value of the key generated in the previous step.
You must restart the OpenAM server after changing Advanced properties.
Install on OpenIG host listening on port 8080.
/etc/hosts or equivalent with a
mapping of demo.forgerock.com to 127.0.0.1. This example
assumes the browser and OpenIG are on the same host. If the
browser is on a different host you must create a mapping so that
all requests to demo.forgerock.com are resolved to the OpenIG
host.
To test, startup Tomcat and make sure you can browse to http://demo.forgerock.com:8080 and get the Tomcat home page. If you get a different page, then you have not modified your host file settings correctly. demo.forgerock.com should resolve to either localhost or the host OpenIG where is running.
Install on the OpenIG host on Tomcat at http://demo.forgerock.com:8080
OpenSSO server URL: http://www.idp.com:8888/openam
Install agent filter in global web.xml true
Agent URL: http://demo.forgerock.com:8080/agentapp
To test, startup Tomcat and browse to the request headers
example at
http://demo.forgerock.com:8080/examples/servlets/servlet/RequestHeaderExample.
You should be redirected to OpenAM for authentication. Once logged in
as user george with password
constanza you should be redirected back to the
examples page and be able to see the user name and replay password
headers. The user name header should be george, the password header
should be encrypted.
See Installing
OpenIG for instructions, and have your
container listen on port 8080. Install OpenIG in the root context by
removing the existing root context directory
$HOME/tomcat/webapps/ROOT/ and then renaming the OpenIG
.war to $HOME/tomcat/webapps/ROOT.war.
Download the WordPressDecryptHeaderLogin.json configuration file, and use it to
replace $HOME/.ForgeRock/OpenIG/config.json.
Search for and replace DESKEY with the key
generated when you enabled the password capture feature in OpenAM.
Restart OpenIG after making changes to
config.json.
Browse to WordPress. If you are not already logged into OpenAM you
should be redirected to the OpenAM login page. You should login with user
name george and password constanza.
After login you should be redirected back to the WordPress portal homepage.
Now click on the login link and OpenIG logs you in as George Costanza.
To see what is happening behind the scenes, take a look at
$HOME/.ForgeRock/OpenIG/config.json. Look for the
HandlerServlet. This is the servlet entry point to OpenIG. Notice it is
calling the DispatchHandler. The DispatchHandler has a condition which
checks for the presence of wp-login.php (the login
page) in the URI path. If the condition is false (no login page), the
ClientHandler is called sending the request on to the WordPress. If the
condition is true, the Gateway has found the login page, and calls the
LoginChain for further processing. The LoginChain calls its filters, the
CryptoFilter, which looks for the replay password header and decrypts it,
the LoginRequestFilter, which creates the login form, and then calls the
ClientHandler to send the form to the WordPress. If you look at the
LoginRequestFilter, you notice it defines the method, URI, and form
parameters for the request which is sent by the ClientHandler. In the
form parameters you see the user name and password retrieved from the user
name and replay password headers in the HTTP request. These headers are
created by the OpenAM agent from the user's OpenAM session and the replay
password header is decrypted by the CryptoFilter prior to the
LoginRequestFilter being executed.