API security with OAuth 2.0 and the ForgeRock Identity Cloud

This example sets up OAuth 2.0, using the standard introspection endpoint, where ForgeRock Identity Cloud is the authorization server, and Identity Gateway is the resource server.

For more information about Identity Gateway as an OAuth 2.0 resource server, refer to Validate access tokens through the introspection endpoint.

This procedure uses the Resource Owner Password Credentials grant type. According to information in the The OAuth 2.0 Authorization Framework, minimize use of this grant type and utilize other grant types whenever possible.

Before you start, prepare Identity Cloud, IG, and the sample application as described in Example installation for this guide.

Set up Identity Cloud:

Log in to the Identity Cloud admin UI as an administrator.
Go to Identities > Manage > Alpha realm - Users, and add a user with the following values:
- Username: demo
- First name: demo
- Last name: user
- Email Address: demo@example.com
- Password: Ch4ng3!t
Make sure you are managing the alpha realm. If not, click the current realm at the top of the screen, and switch realm.
Add a web application:
1. In the Identity Cloud admin UI, click Applications > Add Application > Web, and add a web application with the following values:
  - Client ID: oauth2-client
  - Client Secret: password
2. On the application page, add the following general settings:
  - Grant Types: Resource Owner Password Credentials
  - Scopes: mail
Register an IG agent with the following values, as described in Register an IG agent in Identity Cloud:
- ID: ig_agent
- Password: password

(Optional) Authenticate the agent to Identity Cloud as described in Authenticate an IG agent to Identity Cloud.

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

Set up Identity Gateway:

Set an environment variable for the IG agent password, and then restart IG:
```
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='
```
The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.

Add the following route to Identity Gateway, replacing the value for the property amInstanceUrl:

Linux
Windows

$HOME/.openig/config/routes/oauth2rs-idc.json

appdata\OpenIG\config\routes\oauth2rs-idc.json

{
  "name": "oauth2rs-idc",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/oauth2rs-idc')}",
  "properties": {
    "amInstanceUrl": "https://myTenant.forgeblocks.com/am"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "url": "&{amInstanceUrl}",
        "realm": "/alpha",
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1"
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "OAuth2ResourceServerFilter-1",
          "type": "OAuth2ResourceServerFilter",
          "config": {
            "scopes": [
              "mail"
            ],
            "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>"
        }
      }
    }
  }
}

Notice the following features of the route compared to rs-introspect.json in Validate access tokens through the introspection endpoint, where a local Access Management instance is the authorization server:

The AmService URL points to Access Management in the Identity Cloud.
The AmService realm points to the realm where you have configured your web application and the IG agent.

Test the setup:

In a terminal, export an environment variable for URL of Access Management in the Identity Cloud:
```
$ export amInstanceUrl='myAmInstanceUrl'
```

Use a curl command similar to the following to retrieve an access token:

$ mytoken=$(curl -s \
--user "oauth2-client:password" \
--data 'grant_type=password&username=demo&password=Ch4ng3!t&scope=mail' \
$amInstanceUrl/oauth2/realms/alpha/access_token | jq -r ".access_token")

Validate the access token returned in the previous step:

$ curl -v http://ig.example.com:8080/oauth2rs-idc --header "Authorization: Bearer ${mytoken}"

{
  active = true,
  scope = mail,
  realm = /alpha,
  client_id = oauth2-client,
  ...
}

IG 2023.6

API security with OAuth 2.0 and the ForgeRock Identity Cloud