API Security With OAuth 2.0 and the ForgeRock Identity Cloud

Set up Identity Cloud:

1. Log in to the ForgeRock Identity Cloud as an administrator.

2. 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

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  Applications >  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

5. Add an Identity Gateway agent:

   1. 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:

1. 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.

2. 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"
   }

3. 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:

1. In a terminal, export an environment variable for URL of Access Management in the Identity Cloud:

   $ export amInstanceUrl='myAmInstanceUrl'

2. 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")

3. 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,
     ...
   }