Getting started with the ForgeRock Identity Cloud REST API: Part 3 - Intelligent Access

rajeshr · July 25, 2023, 2:38pm

This is Part 3 of 8 in the series Getting started with the ForgeRock Identity Cloud REST API.

Intelligent Access

This guide provides examples of running the ForgeRock Identity Cloud Collection Intelligent Access requests using both Postman and curl commands.

Before you begin

This guide assumes that you have already prepared the ForgeRock Identity Cloud Postman Collection environment and run the collection prerequisites. See Part 1 - Introduction and Part 2 - Prerequisite requests for further information.

Example using Postman ~ 5 min

In Postman, select ForgeRock Identity Cloud Postman Collection, and expand the Intelligent Access section.

gs_postman_intelligent_access_expand758×1248 134 KB

The Intelligent Access section has examples for various authentication requirements.

The authentication requirement of Identity Cloud is managed by the Access Management component. This requirement can be as simple as a username/password combination or a complex Multi-Factor Authentication. The “json/authenticate” HTTP endpoint of Identity Cloud informs the user of authentication requirements using a callback mechanism. An example of a simple interactive callback returned to the user from Identity Cloud may expect the user to provide their username and password for completing a journey.
Select Step 1 of the Intelligent Access section and study the following:
- The request type: POST
- The request URL: {{amUrl}}/json/authenticate?authIndexValue={{loginJourney}}
Note that the loginJourney collection variable in the above URL is set to a value “Login”. The value “Login” corresponds to an authentication journey configured in the Identity Cloud alpha realm. So this example authenticates the user against the Login authentication journey.

gs_postman_request_callbacks1600×1023 190 KB
With Intelligent Access > Step 1 selected, click Send.
Examine the JSON response detailing the authentication requirement, which in this instance is a username and a password - NameCallback and PasswordCallback respectively.

gs_postman_intelligent_access_step11600×1016 212 KB
Select Step 2a of the Intelligent Access section and study the request method, the endpoint, headers and body. Click Send.

The response is NameCallback and PasswordCallback.
Examine the Body of the request and note the values for NameCallback and PasswordCallback are set to the values of the variables postmanDemoUsername and postmanDemoPassword.

gs_postman_intelligent_access_step2a1600×1019 221 KB
With Intelligent Access > Step 2a selected, click Send once again.

When the step is run the second time, the Identity Cloud “authenticate” endpoint returns a session token for the authenticated user.

gs_postman_intelligent_access_step2a_response1600×1021 220 KB
Select Step 3 of the Intelligent Access section and study the following:
- The request type: POST
- The request URL: {{amUrl}}/json{{realm}}/sessions?_action=getSessionInfo
- The header section, specifically hovering the mouse over the demoSSOToken variable (which now has value set to the token returned in the earlier call).
gs_postman_intelligent_access_step31600×1020 206 KB
With Intelligent Access > Step 3 selected, click Send.

The JSON response from Identity Cloud has the session details of the user authenticated earlier.

gs_postman_intelligent_access_step3_response1600×1024 252 KB
Select Step 4 of the Intelligent Access section and study the following:
- The request type: POST
- The request URL: {{amUrl}}/json{{realm}}/sessions/?_action=logout
- The header section, specifically hovering the mouse over the demoSSOToken variable (which has a value set to the session token of demo user authenticated earlier).
With Intelligent Access > Step 4 selected, click Send.

The JSON response from Identity Cloud states that the user is successfully logged out.

Examples using curl ~ 5 min

The curl versions of Step 2a, Step 3 and Step 4 of the Intelligent Access section of the ForgeRock Identity Cloud Postman Collection are shown below. The output of the commands are truncated for brevity.

Use the following request to authenticate an endpoint of Identity Cloud, specifically against the Login authentication journey. Identity Cloud returns the callbacks expected.

$ curl --request POST --header 'Content-Type: application/json' --header 'Accept-API-Version: resource=2.0, protocol=1.0' 'https://<id-cloud-tenant>/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=Login' | jq .

Example response:

{
       "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoSW5kZXhWYWx1ZSI6IkxvZ2luIiwi**&lt; ------- output truncated for brevity ----------->** ImlhdCI6MTY4Mjc5NzI1NX0.YTmf25hPsm_MTqhwRNwmU6C4VTcRuimH9mpvMdaJS_s",
       "callbacks": [
         {
           "type": "NameCallback",
           "output": [
            {
               "name": "prompt",
               "value": "User Name"
             }
           ],
           "input": [
             {
               "name": "IDToken1",
               "value": ""
             }
           ],
           "_id": 0
         },
         {
           "type": "PasswordCallback",
           "output": [
             {
               "name": "prompt",
               "value": "Password"
             }
           ],
           "input": [
   {
       "tokenId": "Ps_A70Grx_CPEO7c84X3OhncPPs.*AAJTSQACMDIAAlNLABxLVVRRWDlBVStyN0dtNEhHUVBLZ1QyTUZONDQ9AAR0eXBlAANDVFMAAlMxAAIwMQ..*",
       "successUrl": "/enduser/?realm=/alpha",
       "realm": "/alpha"
     }

Replace the {{authId}} placeholder in the data payload below, fill in the callback elements with appropriate values and send the request to “json/authenticate” endpoint, specifically authenticating against the Login authentication journey. On successful authentication a Session token for the user is returned by Identity Cloud.

$ curl --location 'https://<id-cloud-url>/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=Login' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
--data '{
 "authId": "{{authId}}", 
 "callbacks": [
     {
         "type": "NameCallback",
         "output": [
             {
                 "name": "prompt",
                 "value": "User Name"
             }
         ],
         "input": [
             {
                 "name": "IDToken1",
                 "value": "postmanDemoUser"
             }
         ],
         "_id": 0
     },
     {
         "type": "PasswordCallback",
         "output": [
             {
                 "name": "prompt",
                 "value": "Password"
             }
         ],
         "input": [
             {
                 "name": "IDToken2",
                 "value": "p0stmanD3moPas$word"
             }
         ],
         "_id": 1
     }
 ]
}'

Example response:

{
 "tokenId": "Ps_A70Grx_CPEO7c84X3OhncPPs.*AAJTSQACMDIAAlNLABxLVVRRWDlBVStyN0dtNEhHUVBLZ1QyTUZONDQ9AAR0eXBlAANDVFMAAlMxAAIwMQ..*",
 "successUrl": "/enduser/?realm=/alpha",
 "realm": "/alpha"
}

Send a request to the “sessions” REST endpoint of Identity Cloud to get the user’s session details. Replace the cookie name placeholder with the Cookie name of the Identity Cloud instance and the tokenId placeholder with the user’s session token received above.

To find the Cookie name of the Identity Cloud tenant, log in to the Identity Cloud tenant as administrator, click on Tenant settings on the top right corner of the administrator dashboard and look for Global settings > Cookie.

$ curl --request POST  \
--header '<cookie_name>: <tokenId received above>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
 'https://<id-cloud-tenant>/am/json/realms/root/realms/alpha/sessions?_action=getSessionInfo' | jq .

Example response:

{
 "username": "12a0412d-ad97-4798-a46b-58cb96471d8a",
 "universalId": "id=12a0412d-ad97-4798-a46b-58cb96471d8a,ou=user,o=alpha,ou=services,ou=am-config",
 "realm": "/alpha"
 "latestAccessTime": "2023-04-29T19:48:58Z",
 "maxIdleExpirationTime": "2023-04-29T20:18:58Z",
 "maxSessionExpirationTime": "2023-04-29T21:48:57Z",
 "properties": {
"AMCtxId": "008c1626-7d16-490b-a065-4aa6e6aeac93-2304205"
 }
}

Send a request to the “sessions” REST endpoint of Identity Cloud to log the user out. Replace the cookie name placeholder with the Cookie name of Identity Cloud instance and the tokenId placeholder with the user’s session token.

$ curl --request POST \
--header '<cookie name>: <tokenId>'  \
--header 'Accept-API-Version: resource=3.1, protocol=1.0' 'https://<id-cloud-tenant>/am/json/realms/root/realms/alpha/sessions/?_action=logout' | jq .

Response:

{
 "result": "Successfully logged out"
}

Getting started with the ForgeRock Identity Cloud REST API: Part 3 - Intelligent Access

Intelligent Access

Before you begin

Example using Postman ~ 5 min

Examples using curl ~ 5 min

Further reading