SessionInfoFilter

This filter calls the AM endpoint for session information, and makes the data available as a new context to downstream IG filters and handlers. For information, see "SessionInfoContext".

Supported with AM 5 and later versions.

WebSocket Notifications for Sessions

When WebSocket notifications are set up for sessions, IG receives a notification from AM when a user logs out of AM, or when the AM session is modified, closed, or times out. IG then evicts entries that are related to the event from the sessionCache.

For information about setting up WebSocket notifications, using them to clear the session cache, and including them in the server logs, see "WebSocket Notifications".

Usage

{
  "name": string,
  "type": "SessionInfoFilter",
  "config": {
    "amService": AmService reference,
    "ssoToken": runtime expression<string>
  }
}

Properties

"amService": AmService reference, required

The AmService heap object to use for the following properties:

  • agent, the credentials of the IG agent in AM. When the agent is authenticated, the token can be used for tasks such as getting the user's profile, making policy evaluations, and connecting to the AM notification endpoint.

  • url, the URL of an AM service to use for session token validation and authentication.

  • amHandler, the handler to use when communicating with AM to validate the token in the incoming request.

  • realm: Realm of the IG agent in AM.

  • version: The version of the AM server.

  • sessionProperties, the list of user session properties to retrieve from AM.

    The following properties are retrieved:

    • When sessionProperties in AmService is configured, listed session properties with a value.

    • When sessionProperties in AmService is not configured, all session properties with a value.

    • Properties with a value that are required by IG but not specified by sessionProperties in AmService. For example, when the session cache is enabled, session properties related to the cache are automatically retrieved.

    Properties with a value are returned, properties with a null value are not returned.

This filter is compatible with AM version 5 or higher.

See also, "AmService".

"ssoToken": runtime expression<string>, optional

Location of the AM SSO token. For example, with ${request.headers['mySsoToken'].values[0]} the SSO token is the first value of the mySsoToken header in the request.

Default: ${request.cookies['AmService-ssoTokenHeader'][0].value}, where AmService-ssoTokenHeader is the name of the header or cookie where the AmService expects to find SSO tokens.

Examples

In the following example, the SingleSignOnFilter requires authentication with AM before passing the request along the chain. The SessionInfoFilter collects session info from AM and stores it in the ${contexts.amSession} context. Then the HeaderFilter adds headers containing some of the session info to the request. The session info is then displayed on the home page of the sample application: 

{
  "name": "session-info",
  "baseURI": "http://app.example.com:8081",
  "condition": "${matches(request.uri.path, '^/home/session-info')}",
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "url": "http://openam.example.com:8088/openam",
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "version": "7"
      }
    }
  ],
  "secrets": {
    "stores": [
      {
        "type": "Base64EncodedSecretStore",
        "config": {
          "secrets": {
            "agent.secret.id": "cGFzc3dvcmQ="
          }
        }
      }
    ]
  },
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "SingleSignOnFilter",
          "type": "SingleSignOnFilter",
          "config": {
            "amService": "AmService-1"
          }
        },
        {
          "name": "SessionInfoFilter",
          "type": "SessionInfoFilter",
          "config": {
            "amService": "AmService-1"
          }
        },
        {
          "name": "HeaderFilter",
          "type": "HeaderFilter",
          "config": {
            "messageType": "REQUEST",
            "add": {
              "X-IG-SessionInfo": [ "username: ${contexts.amSession.username}, realm: ${contexts.amSession.realm}, properties: ${contexts.amSession.properties}" ]
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

To try this example:

  1. Add an agent for IG as described in "Set Up an IG Agent in AM".

  2. With AM, IG, and the sample application running, access the route on http://openig.example.com:8080/home/session-info, and then log in to AM as user demo, password Ch4ng31t.

    The home page of the sample application is displayed.

  3. Note that the header x-ig-sessioninfo and its values are displayed: 

    x-ig-sessioninfo: username: demo, realm: /, properties: {Locale=...
...
UserToken=demo}

To capture additional session properties from AM:

  1. On AM, as admin, and add the property user-status to the Session Property Whitelist Service. For information, see Session Property Whitelist Service in AM's Reference.

  2. Post the value gold to user-status: 

    $ curl --request POST --header "iPlanetDirectoryPro: token" \
--header 'Accept-API-Version: resource=2.0' \
--header "Content-Type: application/json" \
'http://openam.example.com:8088/openam/json/sessions/?_action=updateSessionProperties' \
--data '{"user-status":"gold"}'

    Where iPlanetDirectoryPro is the name of the default AM session cookie, and token is its value. To find the name of your AM session cookie, see "Find the Name of Your AM Session Cookie".

  3. On IG, access the route and note that user-status is displayed: 

    x-ig-sessioninfo: username: demo, realm: /, properties: {...
user-status=gold
...}

Read a different version of :