--- title: API security with OAuth 2.0 and the Advanced Identity Cloud description: This example sets up OAuth 2.0, using the standard introspection endpoint, where Advanced Identity Cloud is the authorization server, and Identity Gateway is the resource server. component: pinggateway version: 7.2 page_id: pinggateway:identity-cloud-guide:oauthrs canonical_url: https://docs.pingidentity.com/pinggateway/2026/aic/oauthrs.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2022-05-23T16:04:11Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/aic/oauthrs.html --- # API security with OAuth 2.0 and the Advanced Identity Cloud This example sets up OAuth 2.0, using the standard introspection endpoint, where Advanced 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, see [Validate access tokens through the introspection endpoint](../gateway-guide/oauth2-rs.html#oauth2-rs-introspect). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This procedure uses the *Resource Owner Password Credentials* grant type. According to information in the [The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749#section-10.7), minimize use of this grant type and utilize other grant types whenever possible. | Before you start, prepare Advanced Identity Cloud, IG, and the sample application as described in [Example installation for this guide](preface.html#preface-examples). 1. Set up Advanced Identity Cloud: 1. Log in to Advanced Identity Cloud as an administrator. 2. 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` 3. Make sure that you are managing the `alpha` realm. If not, click the current realm at the top of the screen, and switch realm. 4. Add a web application: 1. In the platform console, click [icon: th, set=fa]Applications > [icon: plus, set=fa]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` 1) Click [icon: verified_user, set=material, size=inline] Gateways & Agents, and add an agent profile with the following values: * ID: `ig_agent` * Password: `password` By default, the agent can introspect OAuth 2.0 tokens issued to any client, in the realm and subrealm where it is created. To change the introspection, select [icon: open_in_new, set=material, size=inline] Native Consoles > Access Management, and update the agent in the AM console. 2. Set up Identity Gateway: 1. Set an environment variable for the IG agent password, and then restart IG: ```bash $ export AGENT_SECRET_ID='cGFzc3dvcmQ=' ``` The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded. 2. 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 ``` ```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", "version": "7.2", "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": "

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

" } } } } } ``` Notice the following features of the route compared to `rs-introspect.json` in [Validate access tokens through the introspection endpoint](../gateway-guide/oauth2-rs.html#oauth2-rs-introspect), where a local Access Management instance is the authorization server: * The AmService `URL` points to Access Management in the Advanced Identity Cloud. * The AmService `realm` points to the realm where you have configured your web application and the IG agent. 3. Test the setup: 1. In a terminal, export an environment variable for URL of Access Management in the Advanced Identity Cloud: ```bash $ export amInstanceUrl='myAmInstanceUrl' ``` 2. Use a `curl` command similar to the following to retrieve an access token: ```bash $ 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: ```bash $ curl -v http://ig.example.com:8080/oauth2rs-idc --header "Authorization: Bearer ${mytoken}" { active = true, scope = mail, realm = /alpha, client_id = oauth2-client, ... } ```