Getting Started with Scripting in ForgeRock Identity Cloud: Part 5 - Adding user profile attributes to a user session

[rajeshr]

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

Adding user profile attributes to a user session ~ 10 minutes

In the previous example (in part 4), a Journey Decision Node script added a static property and its value to a user’s session. In some instances, applications might expect an attribute from the user’s profile to be available in the user’s session (token).

In ForgeRock Identity Cloud, a script can access user profile data through the methods of the idRepository object. For example, the following line of code returns the first name (givenName) of the named Identity Cloud user:

idRepository.getAttribute(username,givenName)

The script example (session-property script) is modified to include additional lines to:

• retrieve the "username" from shared state
• fetch the user’s profile attribute "fr-attr-istr1" using the getAttribute method of idRepository object
• add the user’s profile attribute fetched as a session property

var username=sharedState.get("username") 
var attribute="fr-attr-istr1" 
var profileAttribute=String(idRepository.getAttribute(username,attribute)) 
var goTo = org.forgerock.openam.auth.node.api.Action.goTo 
action = goTo("true").putSessionProperty("mySessionProperty", profileAttribute).build() 

In the example above, the user profile attribute to be included in the user’s session is "fr-attr-istr1".

It is important to keep in mind that a profile attribute of an Identity Cloud user might be referenced differently by the Access Management (AM) and the Identity Management (IDM) components of Identity Cloud. For example, the user attribute "frIndexedString1" managed by the IDM component of Identity Cloud is referenced as the "fr-attr-istr1" attribute by the AM component of Identity Cloud. The various Identity Cloud user profile attributes and how they are referenced by the AM and the IDM components are available in the User Identity Attributes and Properties Reference table.

NOTE: If the session property is changed from "mySessionProperty" to any other value in the code above, don’t forget to include it in the session allowlist as discussed in the whitelisting session properties in Identity Cloud.

Overview

This guide takes you through the following steps:

• Modify the session-property script
• Modify the pwdGrant journey
• Update the user’s profile
• Test the journey
• Script modifications

Modifying the session-property script

1. In the Identity Cloud admin UI, go to /alpha > Scripts > Auth Scripts > session-property.

2. Replace the “session-property” script with the code below and click Save and Close.

   var username=sharedState.get("username") 
   var attribute="fr-attr-istr1" 
   var profileAttribute=String(idRepository.getAttribute(username,attribute)) 
   var goTo = org.forgerock.openam.auth.node.api.Action.goTo 
   action = goTo("true").putSessionProperty("mySessionProperty", profileAttribute).build()   
   

   

Modifying the pwdGrant journey

1. In the Identity Cloud admin UI, go to /alpha > Journeys > PwdGrant.

2. On the PwdGrant journey edit page, click on the Data Store Decision node, and delete it from the journey using the “trash” icon.

   

3. Drag the Identity Store Decision (Basic Authentication) node on to the canvas.

4. In the Identity Store Decision node properties window, select Username as Universal Identifier.

   

5. Connect the nodes as shown in the following screenshot and click Save.

   

Updating the user’s profile

1. In the Identity Cloud admin UI, navigate to /alpha > Identities > Manage > fruser10.

2. Update the value of Generic Indexed String 1 to “Engineering” and click Save.

   

Testing the journey

Using the curl examples used previously (in part 4), authenticate the user against the pwdGrant journey and introspect the session.

1. Authenticate 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": "ztf5zGTsiRFJSAnB95fAGUSziVw.*AAJTSQACMDIAAlNLABxVK1hVMVFESjRaRitjMTltUWl6WGxrTEFHZVk9AAR0eXBlAANDVFMAAlMxAAIwMQ..*", 
        "successUrl": "/enduser/?realm=/alpha", 
        "realm": "/alpha" 
      }
   

2. Get the session details:

   $ 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>'  | jq . 
   

   Example response:

    { 
          "username": "a3655285-d900-4833-a92b-6dd1f9b07b22", 
          "universalId": "id=a3655285-d900-4833-a92b-6dd1f9b07b22,ou=user,o=alpha,ou=services,ou=am-config", 
          "realm": "/alpha", 
          "latestAccessTime": "2023-05-14T08:43:30Z", 
          "maxIdleExpirationTime": "2023-05-14T09:13:30Z", 
          "maxSessionExpirationTime": "2023-05-14T10:43:29Z", 
          "properties": { 
        	  "AMCtxId": "98895ad5-7857-4062-b193-aa3ca16edd95-479500", 
        	  "mySessionProperty": "[Engineering]" 
          } 
     } 
   

Script modifications

1. Note that in the above response from Identity Cloud, the profile attribute returned as the session property value is a hash set. Make the following minor change in the “session-properties” script to get the profile attribute returned as an element:

   var profileAttribute=String(idRepository.getAttribute(username,attribute).toArray()[0]) 
   

   After saving the above change, if a user is authenticated against the pwdGrant journey, the session
   introspection response looks as follows:

    { 
         "username": "a3655285-d900-4833-a92b-6dd1f9b07b22", 
         "universalId": "id=a3655285-d900-4833-a92b-6dd1f9b07b22,ou=user,o=alpha,ou=services,ou=am-config", 
         "realm": "/alpha", 
         "latestAccessTime": "2023-05-14T09:19:19Z", 
         "maxIdleExpirationTime": "2023-05-14T09:49:19Z", 
         "maxSessionExpirationTime": "2023-05-14T11:19:18Z", 
         "properties": { 
       	"AMCtxId": "98895ad5-7857-4062-b193-aa3ca16edd95-527704", 
       	"mySessionProperty": "Engineering" 
         } 
     } 
   

2. The various states like sharedState, transientState, etc. are encapsulated in a Java class named NodeState. A script invoked from a Scripted Decision node in an authentication journey can use appropriate methods of the NodeState object to access the shared state of the journey. For example, use the following code to retrieve username from the shared state using the NodeState object:

   var username=nodeState.get("username").asString() 
   

   The modified session-properties script looks like this:

   

Test the pwdGrant journey again using the REST API and confirm the script produces the desired result.

The script examples in this guide used a few Access Management contexts via AM bindings like callbacks, idRepository and nodeState. A Scripted Decision node script has access to many more AM bindings, objects that AM injects into the script execution context. For further information, see Scripted Decision node bindings.

Further reading

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

• Part 1 - Introduction
• Part 2 - Adding a scripted node to a journey
• Part 3 - Capturing user login time
• Part 4 - Adding properties to user session

Other useful links:

• Scripting
• Reference user identity attributes and properties
• Scripted Decision node bindings

Please provide us your feedback on this guide.