--- title: OAuth 2.0 and PingOne Advanced Identity Cloud description: Configure PingGateway as an OAuth 2.0 resource server with PingOne Advanced Identity Cloud as the Authorization Server using token introspection component: pinggateway version: 2026 page_id: pinggateway:aic:oauthrs canonical_url: https://docs.pingidentity.com/pinggateway/2026/aic/oauthrs.html revdate: 2025-10-15T18:45:22Z keywords: ["Single sign-on (SSO)", "Security", "Authenticate", "OAuth 2.0"] page_aliases: ["identity-cloud-guide:oauthrs.adoc"] --- # OAuth 2.0 and PingOne Advanced Identity Cloud 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. Learn about PingGateway as an OAuth 2.0 resource server in [Validating PingAM access tokens with introspection](../gateway-guide/oauth2-rs-introspect.html). | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This procedure uses the *Resource Owner Password Credentials* grant type. As suggested in [The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749#section-10.7), use 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](preface.html#preface-examples). 1. Set up PingOne Advanced Identity Cloud: 1. Log in to the Advanced Identity Cloud admin UI as an administrator. 2. Make sure you are managing the `alpha` realm. If not, click the current realm at the top of the screen, and switch realm. 3. Go to [icon: group, set=material, size=inline] Identities > Manage > [icon: settings_system_daydream, set=material, size=inline] 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` 4. Go to [icon: th, set=fa]Custom Application > [icon: plus, set=fa]Custom Application > OIDC - OpenId Connect > Web and add a web application with the following values: * Name: `oauth2-client` * Owners: `demo user` * Client Secret: `password` * (Optional) Use Secret Store for password: Select this to store the password in an ESV secret. If you select this option, enter a Secret Label Identifier. This value represents the `identifier` part of the secret label for the client. PingOne Advanced Identity Cloud uses the identifier to generate a secret label in the following format: `am.applications.oauth2.client.identifier.secret`. To complete the client profile, add an ESV secret for the password and map the ESV to the secret label. To learn more, read [Secret labels](https://docs.pingidentity.com/pingoneaic/tenants/esvs-signing-encryption.html#secret-labels) in the PingOne Advanced Identity Cloud documentation. * 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](https://docs.pingidentity.com/pingoneaic/app-management/applications.html). 5. Register a PingGateway agent with the following values, as described in [Register a PingGateway agent in PingOne Advanced Identity Cloud](preface.html#register-agent-idc): * ID: `ig_agent` * Password: `password` 2. Set up PingGateway: 1. Set up PingGateway for HTTPS, as described in [Configure PingGateway for TLS (server-side)](../installation-guide/securing-connections.html#server-side-tls). 2. Set an environment variable for the PingGateway agent password, and then restart PingGateway: ```console $ export AGENT_SECRET_ID='cGFzc3dvcmQ=' ``` The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded. 3. Add the following route to PingGateway, replacing the value for the property `amInstanceUrl`: * Linux `$HOME/.openig/config/routes/oauth2rs-idc.json` * Windows `%appdata%\OpenIG\config\routes\oauth2rs-idc.json` ```json { "name": "oauth2rs-idc", "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, "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": "

Decoded access_token: ${contexts.oauth2.accessToken.info}

" } } } } } ``` Source: [oauth2rs-idc.json](../_attachments/config/routes/oauth2rs-idc.json) Notice the following features of the route compared to `rs-introspect.json` in [Validating PingAM access tokens with introspection](../gateway-guide/oauth2-rs-introspect.html), 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. 3. Test the setup: 1. In a terminal, export an environment variable for the URL of PingAM in PingOne Advanced Identity Cloud: ```console $ export amInstanceUrl='myAmInstanceUrl' ``` 2. Use a `curl` command similar to the following to retrieve an access token: ```console $ 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") ``` 3. Validate the access token returned in the previous step: ```console $ curl -v \ --cacert /path/to/secrets/ig.example.com-certificate.pem \ --header "Authorization: Bearer ${mytoken}" \ https://ig.example.com:8443/oauth2rs-idc ``` Output ```none { active = true, scope = mail, realm = /alpha, client_id = oauth2-client, ... } ```