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

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:

• Session properties are refreshed when a new session is created (log out, log back in), which means they are not updated when a mapped user attribute is changed. However, you can query the /users endpoint to retrieve the updated user attribute instead. See Reading Identities for further information.
• Mapped LDAP user attributes are retrieved one at a time, which can impact performance if you have a lot of attributes and/or highly loaded systems. This is a known issue:  OPENAM-13788 (AM Session properties can only be added one at a time which is highly inefficient). Possible workarounds are mentioned in  OPENAM-14800 (Session property update is not batched and do per LDAP operation per property).
• The session property whitelist in AM is case-sensitive whereas DS is not. This means it is possible to add both MAIL and mail attributes to the whitelist in AM but only the last attribute entered is stored in DS, which can cause issues as attributes will not be found unless the case matches. This is a known issue: OPENAM-16157 (Session Property Whitelist Service allows case variant Property Names but DS is not casesensitive), which is resolved in AM 6.5.3, and AM 7.0.1 or later. You should ensure you always use the correct case when specifying the property name in AM so that it matches what is stored in DS. For example, the attribute AuthLevel is not found if you try to retrieve authlevel.

Configuring the user attributes and/or whitelist

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.)