How To

ForgeRock Identity Platform

Does not apply to Identity Cloud

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

Last updated Jan 16, 2023

The purpose of this article is to provide information on validating session tokens and obtaining session details, such as the remaining session time and the idle session time, using the REST API in AM. You can also reset the idle time for a session using the REST API.

2 readers recommend this article

Overview

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.

You can perform the following session related tasks using the REST API:

Check session details
Reset the idle time for a session
Check the session details configured in a specific realm
Check the authentication level

The following Postman collection has been provided to make it easier to perform these session related tasks: Check Session Details AM5.5.postman_collection.json

You will need to edit the Headers for the Authenticate request to provide your credentials, specify the tokenID of the session you are checking in the body and specify the realm as a URL parameter if you are checking session details in a realm. See How do I use the Postman collections that are provided for AM (All versions)? for further information on installing Postman and using a collection.

Authentication

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

You can inspect 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 inspect someone else's token by passing the admin token in the iPlanetDirectoryPro header and the user's token in the tokenId parameter.

For example, to authenticate as an admin user:

$ 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": "/" }

Checking session details

You can check the following session details using a single curl command:

Is session active
Maximum session time configured
Maximum idle time configured
How long a session has been idle

Note

Any user attributes or session properties that have been added to the allowlist are also returned when you call this endpoint. See Session Property Whitelist service and the Checking the authentication level section below for further information.

In AM 6.5.3 and later, you can use the getSessionInfoAndResetIdleTime endpoint instead if you want to reset the idle timeout when checking the session details. See Get information about sessions over REST for further information.

You can check these details using the following curl command, where the tokenId value is the token of the session you are checking; if it is your own session, you only need to pass your token in 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=getSessionInfo

Example response:

{ "username": "demo", "universalId": "id=demo,ou=user,dc=am,dc=forgerock,dc=org", "realm": "/", "latestAccessTime": "2019-02-25T11:08:36Z", "maxIdleExpirationTime": "2019-02-25T11:38:36Z", "maxSessionExpirationTime": "2019-02-25T12:45:10Z", "properties": {} }

If the session is not active, you will see the following response instead:

{ "valid": false }

Resetting the idle time for a session

You can reset the idle time for a server-side session using the following curl command, where the tokenId value is the token of the session you are resetting; if it is your own session, you only need to pass your token in 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=refresh

Example response:

{ "uid": "demo", "realm": "/", "idletime": 21, "maxidletime": 30, "maxsessiontime": 120, "maxtime": 6973 }

Note

AM does not monitor idle time for client-side sessions, which means you cannot reset the idle time for a client-side session tokenId.

Checking session details configured in a specific realm

You can check the maximum session time and maximum idle time that has been configured (in minutes) in a specific realm using the following curl command, where myRealm in the URL is the name of the realm you are checking:

$ curl -X GET -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" "https://am.example.com:8443/am/json/realms/root/realms/myRealm/realm-config/services/session

Example response:

{ "_id": "", "_rev": "-548141562", "dynamic": { "maxSessionTime": 120, "maxIdleTime": 30, "quotaLimit": 5, "maxCachingTime": 3 }, "_type": { "_id": "session", "name": "Session", "collection": false } }

Caution

This command will only return a response if the Session service has been added to the realm, otherwise you will get a 404 Not Found response.

Checking the authentication level

You can check the authentication level for a session providing you have added AuthLevel to the Session Property Whitelist to allow it to be read. See Session Property Whitelist service for further information. Once this property is added to the allowlist, it is also returned when using the json/sessions?_action=getSessionInfo endpoint (see the Check session details section above).

Note

See How do I retrieve user attributes from a session using the REST API in AM (All versions)? for details of other user attributes / session properties you can retrieve from sessions.

You can then check the authentication level for a session using the following curl command, where the tokenId value is the token of the session you are checking; if it is your own session, you only need to pass your token in 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:

{"AuthLevel":"0"}

Related Training

N/A

Related Issue Tracker IDs

N/A