Validate access tokens with introspection

This page sets up PingGateway as an OAuth 2.0 resource server using the introspection endpoint.

For more information about configuring AM as an OAuth 2.0 authorization service, refer to AM’s OAuth 2.0 guide.

This procedure uses the Resource Owner Password Credentials grant type. As suggested in The OAuth 2.0 Authorization Framework, use other grant types whenever possible.

Before you start, prepare AM, PingGateway, and the sample application as described in Example installation for this guide.

Set up AM:

Select Applications > Agents > Identity Gateway, and register a PingGateway agent with the following values:
- Agent ID: ig_agent
- Password: password
- Token Introspection: Realm Only
  
  Use secure passwords in a production environment. Consider using a password manager to generate secure passwords.

(Optional) Authenticate the agent to AM as described in Authenticate a PingGateway agent to AM.

PingGateway agents are automatically authenticated to AM by a deprecated authentication module in AM. This step is currently optional, but will be required when authentication chains and modules are removed in a future release of AM.

Create an OAuth 2.0 Authorization Server:
1. Select Services > Add a Service > OAuth2 Provider.
2. Add a service with the default values.
Create an OAuth 2.0 Client to request OAuth 2.0 access tokens:
1. Select Applications > OAuth 2.0 > Clients, and add a client with the following values:
  - Client ID: client-application
  - Client secret: password
  - Scope(s): mail, employeenumber
2. (Optional) On the Core tab, switch to using a client secret associated with a secret label by setting a Secret Label Identifier and mapping the label to a secret.
  
  To learn more, read Create a client profile and Map and rotate secrets in the AM documentation.
3. On the Advanced tab, select the following value:
  - Grant Types: Resource Owner Password Credentials

Set up PingGateway

Set up PingGateway for HTTPS, as described in Configure PingGateway for TLS (server-side).
Set an environment variable for the PingGateway agent password, and then restart PingGateway:
```
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='
```
The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.

Add the following route to PingGateway:

Linux
Windows

$HOME/.openig/config/routes/rs-introspect.json

%appdata%\OpenIG\config\routes\rs-introspect.json

{
  "name": "rs-introspect",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/rs-introspect$')}",
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "url": "http://am.example.com:8088/openam/"
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "OAuth2ResourceServerFilter-1",
          "type": "OAuth2ResourceServerFilter",
          "config": {
            "scopes": [
              "mail",
              "employeenumber"
            ],
            "requireHttps": false,
            "realm": "OpenIG",
            "accessTokenResolver": {
              "name": "TokenIntrospectionAccessTokenResolver-1",
              "type": "TokenIntrospectionAccessTokenResolver",
              "config": {
                "amService": "AmService-1",
                "providerHandler": {
                  "type": "Chain",
                  "config": {
                    "filters": [
                      {
                        "type": "HttpBasicAuthenticationClientFilter",
                        "config": {
                          "username": "ig_agent",
                          "passwordSecretId": "agent.secret.id",
                          "secretsProvider": "SystemAndEnvSecretStore-1"
                        }
                      }
                    ],
                    "handler": "ForgeRockClientHandler"
                  }
                }
              }
            }
          }
        }
      ],
      "handler": {
        "type": "StaticResponseHandler",
        "config": {
          "status": 200,
          "headers": {
            "Content-Type": [ "text/html; charset=UTF-8" ]
          },
          "entity": "<html><body><h2>Decoded access_token: ${contexts.oauth2.accessToken.info}</h2></body></html>"
        }
      }
    }
  }
}

For information about how to set up the PingGateway route in Studio, see Token validation using the introspection endpoint in Structured Editor.

Notice the following features of the route:

The route matches requests to /rs-introspect.
The OAuth2ResourceServerFilter expects an OAuth 2.0 access token in the authorization header of the incoming authorization request, with the scopes mail and employeenumber.

The accessTokenResolver uses the AM server declared in the heap. The introspection endpoint to validate the access token is extrapolated from the URL of the AM server.

For convenience in this test, requireHttps is false. In production environments, set it to true.
After the filter validates the access token, it creates a new context from the Authorization Server response. The context is named oauth2, and can be reached at contexts.oauth2 or contexts['oauth2'].

The context contains information about the access token, which can be reached at contexts.oauth2.accessToken.info. Filters and handlers further down the chain can access the token info through the context.

If there is no access token in the request, or token validation does not complete successfully, the filter returns an HTTP error status to the user agent, and PingGateway does not continue processing the request. This is done as specified in the RFC, The OAuth 2.0 Authorization Framework: Bearer Token Usage.
The HttpBasicAuthenticationClientFilter adds the credentials to the outgoing token introspection request.
The StaticResponseHandler returns the content of the access token from the context ${contexts.oauth2.accessToken.info}.

Test the setup:

In a terminal window, use a curl command similar to the following to retrieve an access token:

$ mytoken=$(curl -s \
--user "client-application:password" \
--data "grant_type=password&username=demo&password=Ch4ng31t&scope=mail%20employeenumber" \
http://am.example.com:8088/openam/oauth2/access_token | jq -r ".access_token")

Validate the access token returned in the previous step:

$ curl -v \
--cacert /path/to/secrets/ig.example.com-certificate.pem \
--header "Authorization: Bearer ${mytoken}" \
https://ig.example.com:8443/rs-introspect

{
  active = true,
  scope = employeenumber mail,
  realm=/,
  client_id = client-application,
  user_id = demo,
  token_type = Bearer,
  exp = 158...907,
  ...
}

PingGateway 2024.9

Validate access tokens with introspection