How do I retrieve user attributes from a session using the REST API in AM (All versions)?
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.
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.
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:
- 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"
- 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:
- 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": "/" }
- 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*"
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)?
Getting and Setting Session Properties Using REST
Validating Sessions Using REST
Related Training
N/A