Getting Started with Scripting in ForgeRock Identity Cloud: Part 4 - Adding properties to user session

rajeshr · September 7, 2023, 4:00pm

This is Part 4 of 5 in the series Getting started with Scripting in ForgeRock Identity Cloud.

Adding properties to a user session ~ 10 minutes

On successful authentication, a session is created for the authenticated user. Sometimes certain applications in an infrastructure expect certain properties/attributes to be made available in a user session. A script can create session properties with the fields and methods of the Action interface.

For example, in the following code snippet, the outcome is set to true using the Action interface in addition to adding a custom session property:

  var goTo = org.forgerock.openam.auth.node.api.Action.goTo 
  action = goTo("true").putSessionProperty("mySessionProperty", "myPropertyValue").build()

Overview

This guide takes you through the following steps:

Creating the script

In the Identity Cloud Admin UI, go to /alpha > Scripts > Auth Scripts > + New Script.
Select Journey Decision Node and click Next.
Provide the following details:

Name: session-property
Description: Script to add custom session property
JavaScript: Replace the placeholder code in the inline editor with code below:
```
 var goTo = org.forgerock.openam.auth.node.api.Action.goTo 
 action = goTo("true").putSessionProperty("mySessionProperty", "myPropertyValue").build()
```
Click Save and Close.

Using the Journey Decision Node script in an authentication journey

In the Identity Cloud admin UI, go to /alpha > Journeys.
Create a PwdGrant journey by choosing PasswordGrant > ⋯ > Duplicate option.
Use the information below as reference to complete the Duplicate Journey form:

Name: PwdGrant
Identity Object: Alpha realm - Users managed/alpha_user
Description: Modified Password Grant journey
Click Save.
Drag the Scripted Decision (Utilities) node on to the PwdGrant journey.
Select the Scripted Decision node.
Give the node a more meaningful name, for example, “Set My Session Property”.
Under the Script drop down, choose the “session-property” script you created earlier.
In Outcomes, type true and hit enter. Notice that the Scripted Decision node now has an outcome that can be connected to other nodes in the journey.

gs_scripts_set_my_session428×844 50.3 KB
Connect the True outcome of the DataStore Decision node to the Scripted Decision node (e.g. Set My Session Property)
Connect the outcome of the Scripted Decision node (Set My Session Property) to the Success node.

Whitelisting session properties in Identity Cloud

The session properties added in a script must be whitelisted by the Access Management component in Identity Cloud.

Perform the steps below to add the session property used in the script to the Session Property Whitelist service.

In the Identity Cloud Admin UI, go to /alpha > Native Consoles > Access Management.

gs_scripts_access_management_menu294×1190 63 KB
In the Access Management admin UI, go to alpha > Services.

gs_scripts_aam_services1600×822 126 KB
If the Session Property Whitelist Service is not already configured, click +Add a Service.

gs_scripts_services1600×816 103 KB
Type to look for and select the “Session Property Whitelist Service”.

gs_scripts_new_service1604×318 42.8 KB
On the Session Property Whitelist Service configuration page, type and add the session property “mySessionProperty”, and click Create.

gs_scripts_new_service11604×368 56.4 KB
On the Session Property Whitelist Service configuration page, type and add “mySessionProperty” in the Allowlisted Session Property Names and click Save Changes.

gs_scripts_whitelist_service1604×388 73.7 KB

Testing the journey

Testing the journey involves introspection of the user’s active session after successful authentication with Identity Cloud. To acquire the user’s session (token) and to later introspect it, the Identity Cloud REST API is the most convenient option.

The REST API is covered in detail in this guide. The following examples use the curl command, available by default in most operating systems to invoke HTTP calls to the Identity Cloud REST endpoints.

The following curl command sends a HTTP POST request to the /authenticate REST endpoint of Identity Cloud, specifically the PwdGrant journey with the credentials of the Identity Cloud user “fruser10”.

On successful authentication, the response from Identity Cloud is a session (token) for the user.

  $ curl --location --request POST 'https://<tenant-fqdn>/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=PwdGrant' \
  --header 'X-OpenAM-Username: fruser10' \
  --header 'X-OpenAM-Password: Rock5tar10$' \
  --header 'Content-Type: application/json' \
  --header 'Accept-API-Version: resource=2.1' | jq .

Example response:

  { 
     "tokenId": "AlbCsbwIkihHpiy-OpeFHvN2yvA.*AAJTSQACMDIAAlNLABw0WEcxQnFubDFtSHJScGhHdEs5OVc0eFhMdkE9AAR0eXBlAANDVFMAAlMxAAIwMQ..*", 
     "successUrl": "/enduser/?realm=/alpha", 
     "realm": "/alpha" 
  }

The session token received above is used in the following REST call to get the user’s session details. The user’s session details in the response from Identity Cloud has the session property mySessionProperty with its value added by the script.

Note that the /sessions endpoint used below expects the cookie name of the Identity Cloud tenant, which can be found by navigating to Tenant settings > Global Settings > Cookie in the Identity Cloud admin UI.

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