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 Aug 18, 2021

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:

Two Postman collections have been provided to make it easier to perform these session related tasks:

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 or as a URL parameter depending on version 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" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleservice

Example response:

{ "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/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 whitelist 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 Obtaining Information About Sessions Using REST for further information.

You can check these details using one of the following curl commands, 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 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=getSessionInfo
  • 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=getSessionInfo&tokenId=BXCCq...NX*1*"

Example response:

{  "username": "demo",   "universalId": "id=demo,ou=user,dc=openam,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 CTS-based session using one of the following curl commands, 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 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=refresh
  • 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=refresh&tokenId=BXCCq...NX*1*"

Example response:

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

AM does not monitor idle time for client-based sessions, which means you cannot reset the idle time for a client-based 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*" "http://host1.example.com:8080/openam/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 whitelist, 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 one of the following curl commands, 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 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:

{"AuthLevel":"0"}

See Also

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

How do I configure session timeouts in AM (All versions)?

FAQ: REST API in AM

Using the REST API in AM

Validating Sessions Using REST

Specifying Realms in REST API Calls

Retrieving Identities Using the Session Cookie

Sessions Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12436 (The ../sessions?_action=validate endpoint always resets the session's idle time)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.
Loading...