Getting Login Credentials From OpenAM

OpenIG helps integrate applications with OpenAM’s password capture and replay feature. This feature of OpenAM is typically used to integrate with Microsoft Outlook Web Access (OWA) or SharePoint by capturing the password during OpenAM authentication, encrypting it, and adding to the session, which is later decrypted and used for Basic Authentication to OWA or SharePoint. In this chapter, you will learn:

  • How OpenAM password capture and replay works

  • To configure OpenIG to obtain credentials from OpenAM authentication

  • To use the credentials to log the user in to a protected application

Detailed Flow

The figure below illustrates the flow of requests for a user who is not yet logged into OpenAM accessing a protected application. After successful authentication, the user is logged into the application with the username and password from the OpenAM login session.

password capture replay

  1. The user sends a browser request to access a protected application.

  2. The OpenAM policy agent protecting OpenIG intercepts the request.

  3. The policy agent redirects the browser to OpenAM.

  4. OpenAM authenticates the user, capturing the login credentials, storing the password in encrypted form in the user’s session.

  5. After authentication, OpenAM redirects the browser…​

  6. …​back to the protected application.

  7. The OpenAM policy agent protecting OpenIG intercepts the request, validates the user session with OpenAM (not shown here), adds the username and encrypted password to headers in the request, and passes the request to OpenIG.

  8. OpenIG retrieves the credentials from the headers, and uses the username and decrypted password to replace the request with an HTTP POST of the login form.

  9. The application validates the login credentials.

  10. The application sends a response back to OpenIG.

  11. OpenIG passes the response from the application back to the user’s browser.

Setup Summary

This tutorial calls for you to set up several different software components:

  • OpenAM is installed on http://openam.example.com:8088/openam.

  • Download and run the minimal HTTP server .jar to use as the application to protect:

    The openig-doc-5.3.0-jar-with-dependencies.jar application listens at http://app.example.com:8081. The minimal HTTP server is run with the java -jar openig-doc-5.3.0-jar-with-dependencies.jar command, as described in Getting Started.

  • OpenIG is deployed in Jetty as described in Getting Started. OpenIG listens at http://openig.example.com:8080.

  • OpenIG is protected by an OpenAM Java EE policy agent also deployed in Jetty. The policy agent is configured to add username and encrypted password headers to the HTTP requests.

Setup Details

In this section, it is assumed that you are familiar with the components involved. For OpenAM and OpenAM policy agent documentation, see https://doc.openidentityplatform.org/openam.

Setting Up OpenAM Server

  1. Install and configure OpenAM on http://openam.example.com:8088/openam with the default configuration. If you use a different configuration, make sure you substitute in the tutorial accordingly.

  2. Create a sample user Subject in the top-level realm with username (ID) george and password costanza.

  3. Test that you can log in to OpenAM with this username (ID) and password.

Preparing the Policy Agent Profile

  1. Create the Java EE agent profile in the top-level realm with the following settings:

    • Server URL: http://openam.example.com:8088/openam

    • Agent URL: http://openig.example.com:8080/agentapp

  2. Edit the policy agent profile to add these settings, making sure to save your work when you finish:

    • On the Global settings tab page under General, change the Agent Filter Mode from ALL to SSO_ONLY.

    • On the Application tab page under Session Attributes Processing, change the Session Attribute Fetch Mode from NONE to HTTP_HEADER.

    • Also on the Application tab page under Session Attributes Processing, add UserToken=username and sunIdentityUserPassword=password to the Session Attribute Mapping list.

Configuring Password Capture

Configure password capture in OpenAM as follows:

  1. Update Authentication Post Processing Classes for password replay:

    • In the console for OpenAM 12 and earlier, under Access Control > / (Top Level Realm) > Authentication, click All Core Settings, and then add com.sun.identity.authentication.spi.ReplayPasswd to the Authentication Post Processing Classes.

    • In the console for OpenAM 13 and later, select the top-level Realm, browse to Authentication > Settings, and then add com.sun.identity.authentication.spi.ReplayPasswd to the Authentication Post Processing Classes.

  2. Generate a DES shared key for the OpenAM Authentication plugin and for OpenIG.

    When you configure password capture and replay, an OpenAM policy agent shares captured passwords with OpenIG. Before communicating the passwords to OpenIG however, OpenAM encrypts them with a shared key. OpenIG then uses the shared key to decrypt the shared passwords. You supply the shared key to OpenIG and to OpenAM as part of the password capture configuration.

    To generate a DES shared key, you can use a DesKeyGenHandler as described in DesKeyGenHandler(5) in the Configuration Reference. Add the route for the handler while you generate the key. For example, add the following route configuration file as $HOME/.openig/config/routes/04-keygen.json:

    {
  "handler": {
    "type": "DesKeyGenHandler"
  },
  "condition": "${matches(request.uri.path, '^/keygen')
                  and (matches(contexts.client.remoteAddress, ':1')
                  or matches(contexts.client.remoteAddress, '127.0.0.1'))}"
}

    On Windows, the file name should be %appdata%\OpenIG\config\routes\04-keygen.json.

    Call the route to generate a key as in the following example:

    $ curl http://localhost:8080/keygen
{"key":"1U+YFlIcDjQ="}

    The shared key is sensitive information. If it is possible for others to inspect the response, make sure you use HTTPS to protect the communication.

  3. In the OpenAM console under Configuration > Servers and Sites, click on the server name link, go to the Advanced tab and add com.sun.am.replaypasswd.key with the value of the key generated in the previous step.

  4. Restart the OpenAM server after adding the Advanced property for the change to take effect.

Installing OpenIG

  1. Install OpenIG in Jetty and run the minimal HTTP server as described in Getting Started.

  2. When you finish, OpenIG should be running in Jetty, configured to access the minimal HTTP server as described in that chapter.

  3. The initial OpenIG configuration file should look like the one used to proxy requests through to the HTTP server and to capture request and response data, as described in Configure OpenIG.

  4. To test your setup, access the HTTP server home page through OpenIG at http://openig.example.com:8080.

    Login as username george, password costanza.

    You should see a page showing the username and some information about the request.

Installing the Policy Agent

  1. Install the OpenAM Java EE policy agent alongside OpenIG in Jetty, listening at http://openig.example.com:8080, using the following hints:

    • Jetty Server Config Directory : /path/to/jetty/etc

    • Jetty installation directory. : /path/to/jetty

    • OpenAM server URL : http://openam.example.com:8088/openam

    • Agent URL : http://openig.example.com:8080/agentapp

  2. After copying agentapp.war into /path/to/jetty/webapps/, also add the following filter configuration to /path/to/jetty/etc/webdefault.xml:

    <filter>
  <filter-name>Agent</filter-name>
  <display-name>Agent</display-name>
  <description>OpenAM Policy Agent Filter</description>
  <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
</filter>

<filter-mapping>
  <filter-name>Agent</filter-name>
  <url-pattern>/replay</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>INCLUDE</dispatcher>
  <dispatcher>FORWARD</dispatcher>
  <dispatcher>ERROR</dispatcher>
</filter-mapping>

  3. To test the configuration, start Jetty, and then browse to http://openig.example.com:8080/replay. You should be redirected to OpenAM for authentication.

    Do not log in, however. You have not yet configured a route to handle requests to /replay.

Configuring OpenIG

  1. Add a new route to the OpenIG configuration to handle OpenAM password capture and replay.

    To add the route, add the following route configuration file as $HOME/.openig/config/routes/04-replay.json:

    {
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "PasswordReplayFilter",
          "config": {
            "loginPage": "${true}",
            "headerDecryption": {
              "algorithm": "DES/ECB/NoPadding",
              "key": "DESKEY",
              "keyType": "DES",
              "charSet": "utf-8",
              "headers": [
                "password"
              ]
            },
            "request": {
              "method": "POST",
              "uri": "http://app.example.com:8081",
              "form": {
                "username": [
                  "${request.headers['username'][0]}"
                ],
                "password": [
                  "${request.headers['password'][0]}"
                ]
              }
            }
          }
        },
        {
          "type": "HeaderFilter",
          "config": {
            "messageType": "REQUEST",
            "remove": [
              "password",
              "username"
            ]
          }
        }
      ],
      "handler": "ClientHandler"
    }
  },
  "condition": "${matches(request.uri.path, '^/replay')}"
}

    On Windows, the file name should be %appdata%\OpenIG\config\routes\04-replay.json.

  2. Change DESKEY to the actual key value that you generated in Configuring Password Capture.

  3. Notice the following features of the new route:

    • The PasswordReplayFilter uses the headerDecryption information to decrypt the password that OpenAM captured and encrypted, and that the OpenAM policy agent included in the headers for the request.

      The resulting headerDecryption object should look something like this, but using the key value that you generated:

      {
    "algorithm": "DES/ECB/NoPadding",
    "key": "ipvvZF2Mj0k",
    "keyType": "DES",
    "charSet": "utf-8",
    "headers": [
        "password"
    ]
}

    • The PasswordReplayFilter retrieves the username and password from the context and replaces your browser’s original HTTP GET request with an HTTP POST login request that contains the credentials to authenticate.

    • The HeaderFilter removes the username and password headers before continuing to process the request.

    • The route matches requests to /replay.

Test the Setup

  1. Log out of OpenAM if you are logged in already.

  2. Access the new route, http://openig.example.com:8080/replay.

  3. If you are not already logged into OpenAM, you should be redirected to the OpenAM login page.

    Log in with username george, password costanza. After login you should be redirected back to the application.