OAuth 2.0

This example sets up OAuth 2.0, using the standard introspection endpoint, where PingOne Advanced Identity Cloud is the Authorization Server and PingGateway is the resource server.

For more information about PingGateway 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 PingOne Advanced Identity Cloud, PingGateway, and the sample application as described in Example installation for this guide.

Set up PingOne Advanced Identity Cloud:

Log in to the PingOne Advanced 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 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
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 PingOne Advanced Identity Cloud’s Application management.
Register a PingGateway agent with the following values, as described in Register a PingGateway agent in PingOne Advanced Identity Cloud:
- ID: ig_agent
- Password: password

(Optional) Authenticate a PingGateway agent to PingOne Advanced Identity Cloud.

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

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, 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 PingAM instance is the Authorization Server:

The AmService URL points to PingAM in PingOne Advanced Identity Cloud.
The AmService realm points to the realm where you have configured your web application and the PingGateway agent.

Test the setup:

In a terminal, export an environment variable for the URL of PingAM in PingOne Advanced 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,
  ...
}

PingGateway 2024.6

OAuth 2.0