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, see "Validating Access_Tokens Through the Introspection Endpoint".
Before you start, prepare Identity Cloud and Identity Gateway as described in "Example Installation for This Guide".
Set up Identity Cloud:
Log in to the ForgeRock Identity Cloud as an administrator.
In the platform console, go to Identities > Manage > Alpha realm - Users, and add a new user with the following values:
Username:
demo
First name:
demo
Last name:
user
Email Address:
demo@example.com
Password:
Ch4ng3!t
Make sure that 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:
In the platform console, click Applications > Add Application > Web, and add a web application with the following values:
Client ID:
oauth2-client
Client Secret:
password
On the application page, add the following general settings:
Grant Types:
Resource owner Password Credentials
Scopes:
mail
Add an Identity Gateway agent:
Click 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, click Native Consoles > Access Management, and update the agent in the AM console.
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 IG, to serve .css and other static resources for the sample application:
$HOME/.openig/config/routes/static-resources.json
%appdata%\OpenIG\config\routes\static-resources.json
{ "name" : "sampleapp_resources", "baseURI" : "http://app.example.com:8081", "condition": "${matches(request.uri.path,'^/css')}", "handler": "ReverseProxyHandler" }
Add the following route to Identity Gateway, replacing the value for the property
amInstanceUrl
:$HOME/.openig/config/routes/oauth2rs-idc.json
%appdata%\OpenIG\config\routes\oauth2rs-idc.json
{ "name": "oauth2rs-idc", "baseURI": "http://app.example.com:8081", "condition": "${matches(request.uri.path, '^/oauth2rs-idc')}", "properties": { "amInstanceUrl": "<myIdentityCloudUrl/am>" }, "heap": [ { "name": "SystemAndEnvSecretStore-1", "type": "SystemAndEnvSecretStore" }, { "name": "AmService-1", "type": "AmService", "config": { "url": "&{amInstanceUrl}", "realm": "/alpha", "version": "7.1", "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" ] }, "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 "Validating 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://openig.example.com:8080/oauth2rs-idc --header "Authorization: Bearer ${mytoken}"
{ active = true, scope = mail, realm = /alpha, client_id = oauth2-client, ... }