OAuth 2.0

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.
Make sure you are managing the alpha realm. If not, click the current realm at the top of the screen, and switch realm.
Go to group Identities > Manage > settings_system_daydream 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
Go to Applications > Custom Application > OIDC - OpenId Connect > Web and add a web application with the following values:
- Name: oauth2-client
- Owners: demo user
- Client Secret: password
- Sign On > Grant Types: Authorization Code, Resource owner Password Credentials
- Sign On > Scopes: mail
  
  For more information, refer to Identity Cloud’s Application management.
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 up IG for HTTPS, as described in Configure IG for HTTPS (server-side).
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 the URL of Access Management in 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 \
--cacert /path/to/secrets/ig.example.com-certificate.pem \
--header "Authorization: Bearer ${mytoken}" \
https://ig.example.com:8443/oauth2rs-idc 

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

Identity Gateway 2024.3

OAuth 2.0