Getting started with the ForgeRock Identity Cloud REST API: Part 5 - Session management

[rajeshr]

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

Session management

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

• Example using Postman ~ 5 min
• Examples using curl ~ 5 min

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

1. In Postman, select the ForgeRock Identity Cloud Postman Collection, and expand the Session Management section.

   

   On completing an authentication journey successfully, Identity Cloud issues a Session Token to the authenticated user. The “/sessions” REST endpoint of Identity Cloud can be used to validate a user’s session, get session properties, and refresh it and/or terminate it (logout).

   Step 1 through to Step 8 of Session Management section demonstrate the following:

   • Authenticates a user at the “/json/authenticate” endpoint, specifically against an authentication journey named PasswordGrant. This journey is available in Identity Cloud by default.

   • The session obtained post authentication is then used at the “/sessions” endpoint to:

     1. Get session information
     2. Reset the Idle Time
     3. Get session properties
     4. Validate the session
     5. Refresh the session
     6. Log the user out

   For a refresher on the examples of “/json/authenticate” and “/sessions” endpoints of Identity Cloud, please refer to this and this guide. See Part 3 - Intelligent Access for further information.

2. Go to Session Management > Step 1 and take note of the REST request endpoint, specifically the authIndexValue that is set to “PasswordGrant”.

3. Click Send.

4. Go to Session Management > Step 2 and take note of:

   • the REST request endpoint
   • the request body that has inputs to the NameCallback and PasswordCallback elements.

5. Click Send.

   The request returns a Session Token ID for the user
   

   

6. Go to Session Management > Step 3 and take note of:

   • the REST request endpoint
   • the request headers, specifically hovering the mouse over {{demoSSOToken}}, which now has a value set to the tokenId received above.

7. Click Send.

8. Examine the JSON response received from Identity Cloud, specifically take note of the maxIdleExpirationTime in the session information received.

9. Go to Session Management > Step 4 and study the following:

   • The request type: POST
   • The request URL: {{amUrl}}/json{{realm}}/sessions?_prettyPrint=true&_action=getsessioninfoandresetidletime
   • The header section, specifically hovering the mouse over the demoSSOToken variable which has a value set to the session token of the demo user authenticated earlier.
     
     

10. With Session Management > Step 4 selected, click Send.

    In addition to the session information received as a JSON response from Identity Cloud, notice the maxIdleExpirationTime is reset to a new value.

    

11. Go to Session Management > Step 5 and study the following:

    • The request type: POST
    • The request URL: {{amUrl}}/json{{realm}}/sessions?_prettyPrint=true&_action=getsessionproperties
    • 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).
    

12. With Session Management > Step 5 selected, click Send.

    The user session properties are returned in the JSON response from Identity Cloud to the call made above.
    

    

13. Go to Session Management > Step 6 and study the following:

    • The request type: POST
    • The request URL: {{amUrl}}/json{{realm}}/sessions?_prettyPrint=true&_action=refresh
    • The header section, specifically hovering the mouse over the demoSSOToken variable which has a value set to the session token of the demo user authenticated earlier.
      
      

14. With Session Management > Step 6 selected, click Send.

    The JSON response from Identity Cloud for the call made above confirms the refresh of the user session.
    

    

15. Go to Session Management > Step 7 and study the following:

    • The request type: POST
    • The request URL: {{amUrl}}/json{{realm}}/sessions?_prettyPrint=true&_action=validate
    • 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).
      
      

16. With Session Management > Step 7 selected, click Send
    

    

    The JSON response from Identity Cloud confirms the validity of the user session.

17. Go to Session Management > Step 8 and take note of:

    • the REST request endpoint, specifically the action parameter
    • the request headers

18. Click Send.

    The user’s session is terminated and logged out.

Examples using curl ~ 5 min

The curl versions of Step 1, Step 2 and Step 7 of the Session Management section are shown below. Some portions of the command outputs are truncated for brevity.

1. Make a request to the “authenticate” endpoint of Identity Cloud against the PasswordGrant authentication journey. Identity Cloud returns the callbacks expected.

   $ curl --location --request POST 'https://<id-cloud-tenant>/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=PasswordGrant' \
   --header 'Content-Type: application/json' \
   --header 'Accept-API-Version: resource=2.1'
   

   Example response:

   {
     "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9 <---output truncated for brevity--->_g4S8ZonK54xIIdf3P9PezPtjFUx2s7boxExroCzAI8",
     "callbacks": [
       {
         "type": "NameCallback",
         "output": [
           {
             "name": "prompt",
             "value": "User Name"
           }
         ],
         "input": [
           {
             "name": "IDToken1",
             "value": ""
           }
         ],
         "_id": 0
       },
       {
         "type": "PasswordCallback",
         "output": [
           {
             "name": "prompt",
             "value": "Password"
           }
         ],
         "input": [
           {
             "name": "IDToken2",
             "value": ""
           }
         ],
         "_id": 1
       }
     ]
   }
   

2. 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 journey. On successful authentication, a session token for the user is returned by Identity Cloud.

   $ curl --location 'https://<id-cloud-tenant>/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=PasswordGrant' \
   --header 'Content-Type: application/json' \
   --header 'Accept-API-Version: resource=2.1, 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
        }
    ]
   }' | jq .
   

   Example response:

   {
     "tokenId": "FFC4yWq8ztkoExBctRZT0DvLgaw.*AAJTSQACMDIAAlNLABxIeXAydk0xemJQNW4vSWgrdnBEcDQ1RU02WDg9AAR0eXBlAANDVFMAAlMxAAIwMQ..*",
     "successUrl": "/enduser/?realm=/alpha",
     "realm": "/alpha"
   }
   

3. Send a request to the “sessions” REST endpoint of Identity Cloud to validate the user’s session. 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.

   $ curl --location --request POST 'https://<id-cloud-tenant>/am/json/realms/root/realms/alpha/sessions?_prettyPrint=true&_action=validate' \
   --header 'Accept-API-Version: resource=1.0' \
   --header 'Content-Type: application/json' \
   --header '<cookie name>: <tokenId received above>' | jq .
   

   Example response:

   {
     "valid": true,
     "sessionUid": "008c1626-7d16-490b-a065-4aa6e6aeac93-3619086",
     "uid": "12a0412d-ad97-4798-a46b-58cb96471d8a",
     "realm": "/alpha"
   }
   

Further reading

Other guides in the Getting started with the ForgeRock Identity Cloud REST API series:

• Part 1 - Introduction
• Part 2 - Prerequisites
• Part 3 - Intelligent Access
• Part 4 - User self-service
• Part 5 - Session management
• Part 6 - Identity profiles & OAuth 2.0 flows
• Part 7 - Managed identities
• Part 8 - Auditing and monitoring

Other useful links:

• REST API
• Intelligent access