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

Last updated Jan 16, 2023

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

Note

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.

Overview

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 allowlist. If you want to retrieve other session properties, you do not need to map them; you just need to add them to the allowlist. 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).
The session property allowlist 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 case sensitive), 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.

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 allowlist

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 the allowlist as follows, where step 1 is only needed if you want to retrieve LDAP user attributes from a session:

Map the required LDAP user attributes to session attributes using either the AM admin UI or ssoadm:
- AM admin UI: 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=am,dc=forgerock,dc=org -f pwd.txt -a sunAMUserAttributesSessionMapping="sn|lastName" sunAMUserAttributesSessionMapping="mail|user.mail"
  - AM 6.x: $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e / -u amadmin -f pwd.txt -a sunAMUserAttributesSessionMapping="sn|lastName" sunAMUserAttributesSessionMapping="mail|user.mail"
Add the user attributes you just specified and/or other session properties to the allowlist using either the AM admin UI or ssoadm:
- AM admin UI: 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=am,dc=forgerock,dc=org -f pwd.txt -a forgerock-session-property-whitelist=am.protected.lastName forgerock-session-property-whitelist=am.protected.user.mail
  - AM 6.x: $ ./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 allowlist 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:

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" https://am.example.com:8443/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleservice Example response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/am/console", "realm": "/" }
Retrieve the user attributes and/or session properties using the following curl command, 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 parameter or the iPlanetDirectoryPro header: $ curl -X POST -H "Content-Type: application/json" -H "Accept-API-Version: resource=3" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -d '{"tokenId" : "BXCCq...NX*1*"}' https://am.example.com:8443/am/json/realms/root/sessions?_action=getSessionProperties

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

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