How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I retrieve user attributes from a session using the REST API in AM (All versions)?

Last updated May 10, 2022

The purpose of this article is to provide information on retrieving user attributes and session properties from a session using the REST API. User attributes and session properties are considered protected properties. The information in this article only applies if you are using authentication chains and modules.


3 readers recommend this article

Overview

The information in this article only applies to authentication chains and modules.

As of AM 6.5.3, you can use the Scripted Decision node (user attributes and session properties) or the Set Session Properties node (session properties only) if you use authentication trees. See Scripted Decision Node and Set Session Properties Node for further information.

This process demonstrates retrieving a user's last name and email address from a session using REST, where the LDAP user attributes are:

  • sn - last name
  • mail - email address

If you want to retrieve LDAP user attributes from a session, you must first map them to session attributes and then add them to the whitelist. If you want to retrieve other session properties, you do not need to map them; you just need to add them to the whitelist. See FAQ: REST API in AM (Q. Can I query protected session properties using the REST API?) for a list of available session properties. 

Caveats

Please be aware of the following caveats:

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains valid resource versions.

See How do I avoid common issues with REST calls in AM (All versions)? for further information.

Configuring the user attributes and/or whitelist

Note

You may need to add the Session Property Whitelist Service if it is not listed under Services by clicking Add a Service and then selecting Session Property Whitelist Service. If you are using ssoadm, you can replace set-realm-svc-attrs in the ssoadm command with add-svc-realm to add this service and set the attributes with the same command.

You can configure user attributes and/or whitelist as follows, where step 1 is only needed if you want to retrieve LDAP user attributes from a session:

  1. Map the required LDAP user attributes to session attributes using either the console or ssoadm:
    • Console: navigate to: Realms > [Realm Name] > Authentication > Settings > Post Authentication Processing > User Attribute Mapping to Session Attribute and specify the map in the following format: userAttribute|sessionAttribute, where sessionAttribute is a name of your choosing. Create individual mappings for each attribute; for example, to map the sn and mail attribute, you would enter something similar to: sn|lastName mail|user.mail
    • ssoadm: enter the following command: $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a sunAMUserAttributesSessionMapping="[userAttribute|sessionAttribute]"replacing [realmname], [adminID], [passwordfile] and [userAttribute|sessionAttribute] with appropriate values, where the sunAMUserAttributesSessionMapping attribute must be specified for each individual mapping. For example, to map the sn and mail attribute, you would use the following command:
      • AM 7 and later: $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e / -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -a sunAMUserAttributesSessionMapping="sn|lastName" sunAMUserAttributesSessionMapping="mail|user.mail"
      • Pre-AM 7: $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e / -u amadmin -f pwd.txt -a sunAMUserAttributesSessionMapping="sn|lastName" sunAMUserAttributesSessionMapping="mail|user.mail"
  2. Add the user attributes you just specified and/or other session properties to the whitelist using either the console or ssoadm:
    • Console: navigate to: Realms > [Realm Name] > Services > Session Property Whitelist Service > Whitelisted Session Property Names and enter each session attribute individually with a prefix of am.protected., for example: am.protected.lastName am.protected.user.mail 
    • ssoadm: enter the following command: $ ./ssoadm set-realm-svc-attrs -s SessionPropertyWhitelistService -e [realmname] -u [adminID] -f [passwordfile] -a forgerock-session-property-whitelist=[sessionAttribute]replacing [realmname], [adminID], [passwordfile] and [sessionAttribute] with appropriate values, where the forgerock-session-property-whitelist attribute must be specified for each individual session attribute. For example, you would use the following command to add the session attributes used in this example:
      • AM 7 and later: $ ./ssoadm set-realm-svc-attrs -s SessionPropertyWhitelistService -e / -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -a forgerock-session-property-whitelist=am.protected.lastName forgerock-session-property-whitelist=am.protected.user.mail
      • Pre-AM 7: $ ./ssoadm set-realm-svc-attrs -s SessionPropertyWhitelistService -e / -u amadmin -f pwd.txt -a forgerock-session-property-whitelist=am.protected.lastName forgerock-session-property-whitelist=am.protected.user.mail

Retrieving the user attributes and/or session properties

You can use the json/sessions?_action=getSessionProperties endpoint to retrieve properties. All properties in your whitelist are returned automatically without needing to specify them individually.

Depending on your use case, you may need to authenticate as an admin user:

  • You can retrieve details about your own token by passing it in the tokenId parameter or in the iPlanetDirectoryPro header. If you don't specify the tokenId parameter, the session in the iPlanetDirectoryPro header is inspected instead. An admin token is not required in this scenario.
  • An admin (amAdmin or a delegated admin) can retrieve details about someone else's token by passing the admin token in the iPlanetDirectoryPro header and the user's token in the tokenId parameter.

You can retrieve these user attributes and/or session properties as follows:

  1. Authenticate as an admin user if needed. For example: $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleservice Example response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }
  2. Retrieve the user attributes and/or session properties using one of the following curl commands, where the tokenId value is the token of the session you are retrieving properties for; if it is your own session, you only need to pass your token in either the tokenId paramter or the iPlanetDirectoryPro header:
    • AM 5.5 and later: $ curl -X POST -H "Content-Type: application/json" -H "Accept-API-Version: resource=3" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -d '{"tokenId" : "BXCCq...NX*1*"}' http://host1.example.com:8080/openam/json/realms/root/sessions?_action=getSessionProperties
    • AM 5 and 5.1.x: $ curl -X POST -H "Content-Type: application/json" -H "Accept-API-Version: resource=2" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" "http://host1.example.com:8080/openam/json/realms/root/sessions?_action=getSessionProperties&tokenId=BXCCq...NX*1*"

Example response:    {"am.protected.lastName": "doe", "am.protected.user.mail": "jdoe@example.com"}

See Also

How do I validate session tokens and obtain session details using the REST API in AM (All versions)?

How do I unlock a user's account using the REST API in AM (All versions)?

Using the REST API in AM

Getting and Setting Session Properties Using REST

Validating Sessions Using REST

Specifying Realms in REST API Calls

Sessions Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-16157 (Session Property Whitelist Service allows case variant Property Names but DS is not casesensitive)

OPENAM-13378 (Authentication Tree does not retrieve User Attributes & Session Properties From Session via REST API.)


Copyright and Trademarks Copyright © 2022 ForgeRock, all rights reserved.