Chapter 8. Tutorial On OpenAM Password Capture & Replay
Prev |  | Next

# Chapter 8. Tutorial On OpenAM Password Capture & Replay

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.

## 8.1. Detailed Flow

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.

[D]

1. 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.

2. User browses to a WordPress page requiring authentication.

3. OpenAM Agent intercepts the request, validates the user session, and populates HTTP headers with the user name and encrypted password from the session.

4. Agent passes the original request with populated headers to OpenIG.

5. OpenIG inspects the request, does not find a match for the WordPress login page, so forwards the request on.

6. WordPress finds no application session and redirects to its login page.

7. OpenIG intercepts, sees the login page, creates the login form with the user name and decrypted password from the headers inserted by the Agent.

8. WordPress validates the login form, returns an application session and the user's home page.

9. WordPress home page returned to the user.

## 8.2. Setup Summary

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.

## 8.3. Setup Details

This section assumes you are familiar with the components involved.

### 8.3.1. OpenAM server

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`.

### 8.3.2. Tomcat Agent Profile

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.

### 8.3.3. Password Capture Configuration

- 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.

### 8.3.4. Tomcat Installation

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.

### 8.3.5. Policy Agent installation

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.

### 8.3.6. Gateway Configuration

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`.

### 8.3.7. Trying It Out

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.

Prev |  | Next
Chapter 7. Tutorial With WordPress | Home | Chapter 9. Using the Federation Gateway