Identity Cloud

Manage sessions using REST

To manage sessions using REST, send requests to the /json/sessions endpoint, as shown in the following examples.

Get information about sessions

To get information about a session, send an HTTP POST request to the /json/sessions/ endpoint, using the getSessionInfo action.

This action returns information about the session token provided in the <session-cookie-name> header by default. To get information about a different session token, include it in the POST body as the value of the tokenId parameter.

The following example shows an administrative user passing their session token in the <session-cookie-name> header. The session token of user bjensen (whose universal ID is 1dff18dc-ac57-4388-8127-dff309f80002) is passed as the value of the tokenId:

$ curl \
--request POST \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=4.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": "BXCCq…​NX*1*" }' \
'https://<tenant-env-fqdn>/am/json/realms/root/sessions/?_action=getSessionInfo'
{
    "username": "demo",
    "universalId": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
    "realm": "/",
    "latestAccessTime": "2020-02-21T14:31:18Z",
    "maxIdleExpirationTime": "2020-02-21T15:01:18Z",
    "maxSessionExpirationTime": "2020-02-21T16:29:56Z",
    "properties": {
        "AMCtxId": "aba7b4f3-16ff-4680-b06a-d7ba237d3730-91932"
    }
}

The getSessionInfo action does not refresh the session idle timeout. To obtain session information about a server-side session and reset the idle timeout, use the getSessionInfoAndResetIdleTime action, as follows:

$ curl \
--request POST \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": "BXCCq…​NX*1*" }' \
'https://<tenant-env-fqdn>/am/json/realms/root/sessions/?_action=getSessionInfoAndResetIdleTime'
{
    "username": "demo",
    "universalId": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
    "realm": "/",
    "latestAccessTime": "2020-02-21T14:32:49Z",
    "maxIdleExpirationTime": "2020-02-21T15:02:49Z",
    "maxSessionExpirationTime": "2020-02-21T16:29:56Z",
    "properties": {
        "AMCtxId": "aba7b4f3-16ff-4680-b06a-d7ba237d3730-91932"
    }
}

  • You cannot reset the idle timeout of a client-side session.

  • The AMCtxId property represents the audit ID for the session. To return the AMCtxId property in the session query response (as in this example) you must include AMCtxId in the Session Properties to return for session queries. In the AM admin UI, go to Realms > Realm Name > Services > Session Property Whitelist Service.

Validate sessions

To check if a session token is valid, send an HTTP POST request to the /json/sessions/ endpoint with the validate action. Provide the session token in the POST data as the value of the tokenId.

Provide the session token of an administrative user in the <session-cookie-name> header.

If you don’t specify a tokenId, this request validates the session in the <session-cookie-name> header.

The following example shows an administrative user validating the session token of bjensen (whose universal ID is 1dff18dc-ac57-4388-8127-dff309f80002):

$ curl \
--request POST \
--header "Content-type: application/json" \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=2.1, protocol=1.0" \
--data '{ "tokenId": "BXCCq…​NX*1*" }' \
'https://<tenant-env-fqdn>/am/json/realms/root/sessions?_action=validate'

If the session token is valid, Identity Cloud returns the user ID and realm:

{
  "valid":true,
  "sessionUid":"209331b0-6d31-4740-8d5f-740286f6e69f-326295",
  "uid":"demo",
  "realm":"/"
}

By default, validating a session resets the session’s idle time, which triggers a write operation to the Core Token Service (CTS) token store. To avoid this, include refresh=false, for example, validate&refresh=false.

Refresh server-side sessions

To reset the idle time of a server-side session, send an HTTP POST request to the /json/sessions/ endpoint, with the refresh action. This action refreshes the session token provided in the <session-cookie-name> header by default. To refresh a different session token, include it in the POST body as the value of the tokenId.

The following example shows an administrative user passing their session token in the <session-cookie-name> header, and the session token of bjensen (whose universal ID is 1dff18dc-ac57-4388-8127-dff309f80002) in the tokenId parameter:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{ "tokenId": "BXCCq…​NX*1*" }' \
'https://<tenant-env-fqdn>/am/json/realms/root/sessions/?_action=refresh'
{
  "uid": "demo",
  "realm": "/",
  "idletime": 17,
  "maxidletime": 30,
  "maxsessiontime": 120,
  "maxtime": 7106
}

On success, Identity Cloud resets the idle time for the server-side session, and returns timeout details of the session.

  • Resetting a server-side session’s idle time triggers a write operation to the CTS token store. To avoid the overhead of write operations to the token store, use the refresh action only if you want to reset a server-side session’s idle time.

  • The idle time of a session is reset subject to the latest access time update frequency. Identity Cloud updates a session’s latest access time at most this often. The default is 60 seconds.

  • Identity Cloud does not monitor idle time for client-side sessions, so you cannot use the tokenId of a client-side session to refresh the session’s idle time.

Invalidate sessions

To invalidate a session, send an HTTP POST request to the /json/sessions/ endpoint with the logout action.

Provide the session token in the POST data as the value of the tokenId and the session token of an administrative user in the <session-cookie-name> header.

The following example shows an administrative user invalidating a session token for bjensen (whose universal ID is 1dff18dc-ac57-4388-8127-dff309f80002):

$ curl \
--request POST \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=logout'
{
    "result": "Successfully logged out"
}

If the token is not valid and cannot be invalidated an error message is returned:

{
  "result": "Token has expired"
}

If you don’t specify a tokenId in the request, the logout action invalidates the session in the <session-cookie-name> header, for example:

$ curl \
--request POST \
--header "<session-cookie-name>: BXCCq…​NX*1*" \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
--header "Content-type: application/json" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=logout'
{
    "result": "Successfully logged out"
}

Invalidate specific sessions

To invalidate specific sessions for a user, first obtain a list of the user’s active sessions. Send an HTTP GET request to the /json/sessions/ endpoint, using the SSO token of an administrative user as the value of the <session-cookie-name> header.

Use a queryFilter to specify the name of the user and the realm to search.

For example, to obtain the list of active sessions for bjensen (whose universal ID is 1dff18dc-ac57-4388-8127-dff309f80002) in the alpha realm, the query filter value would be:

username eq "1dff18dc-ac57-4388-8127-dff309f80002" and realm eq "/alpha"

The query filter value must be URL-encoded when sent over HTTP.

For more information about query filter parameters, refer to Query.

In the following example, there are two active sessions. Note the value of the sessionHandle properties.

$ curl \
--request GET \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions?_queryFilter=username%20eq%20%221dff18dc-ac57-4388-8127-dff309f80002%22%20and%20realm%20eq%20%22%2Falpha%22'
{
  "result": [
    {
      "username": "1dff18dc-ac57-4388-8127-dff309f80002",
      "universalId": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
      "realm": "/alpha",
      "sessionHandle": "shandle:Z-3RNqNRdpP9d…​",
      "latestAccessTime": "2022-12-19T10:48:14.549Z",
      "maxIdleExpirationTime": "2022-12-19T11:18:14Z",
      "maxSessionExpirationTime": "2022-12-19T12:48:14Z"
    },
    {
      "username": "1dff18dc-ac57-4388-8127-dff309f80002",
      "universalId": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
      "realm": "/alpha",
      "sessionHandle": "shandle:A42f4U6zv4klr…​",
      "latestAccessTime": "2022-12-19T10:53:31.780Z",
      "maxIdleExpirationTime": "2022-12-19T11:23:31Z",
      "maxSessionExpirationTime": "2022-12-19T12:53:31Z"
    }
  ],
  "resultCount": 2,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

To log out specific sessions, send an HTTP POST request to the /json/sessions/ endpoint, with the logoutByHandle action. Include an array of the session handles to invalidate as values of the sessionHandles property in the POST body.

Use the SSO token of an administrative user as the value of the <session-cookie-name> header.

This example invalidates the sessions returned by the previous query:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
--data '{
    "sessionHandles": [
        "shandle:Z-3RNqNRdpP9d…​",
        "shandle:A42f4U6zv4klr…​"
    ]
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=logoutByHandle'
{
    "result": {
        "shandle:Z-3RNqNRdpP9d…​": true,
        "shandle:A42f4U6zv4klr…​": true
    }
}

Invalidate all sessions for a user

To invalidate (log out) all sessions for a user, send an HTTP POST request to the /json/sessions/ endpoint with the logoutByUser action, specifying the username in the request payload.

Use an access token as a bearer token in the Authorization HTTP header.

This example logs out all sessions for user bjensen (whose universal ID is 1dff18dc-ac57-4388-8127-dff309f80002):

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header 'Authorization: Bearer <access-token>' \
--header "Accept-API-Version: resource=5.1, protocol=1.0" \
--data '{"username": "1dff18dc-ac57-4388-8127-dff309f80002"}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=logoutByUser'
{
  "result": true
}
This action is called on a specific realm.

Get and set session properties

Use the REST API to read and update properties on users' sessions. Define the properties you want to get and set in the Session Property Whitelist Service configuration.

You can use the REST API to:

  • Get the names of the properties that you can read or update. This is the same set of properties configured in the Session Property Whitelist service.

  • Read and update property values.

The ability to set, change and delete session properties is affected by the session state:

  • For server-side sessions, you can manipulate session properties at any time during the session’s lifetime.

  • For client-side sessions, you can manipulate session properties only during the authentication process, before the user receives the session token from Identity Cloud. For example, you can set or delete properties on a client-side session from within a post-authentication plugin.

Differentiate the user who performs the operation from the session affected by the operation as follows:

  • Specify the session token of the user performing the operation on session properties in the <session-cookie-name> header.

  • Specify the session token of the user whose session is to be read or modified as the tokenId parameter in the body of the REST API call.

  • Omit the tokenId parameter from the body of the REST API call if the session of the user performing the operation is the same session that you want to read or modify.

The following examples assume that you configured a property named LoginLocation in the Session Property Whitelist service.

To retrieve the names and values of the properties you can get or set, send an HTTP POST request to the json/sessions endpoint, with the getSessionProperties action:

$ curl \
--request POST \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": "BXCCq…​NX*1*" }' \
'https://<tenant-env-fqdn>/am/json/realms/root/sessions/?_action=getSessionProperties'
{
    "LoginLocation": ""
}

To set the value of a session property, send an HTTP POST request to the /json/sessions/ endpoint, with the updateSessionProperties action. If you do not specify a tokenId parameter in the request body, the operation affects the session specified in the <session-cookie-name> header:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"LoginLocation":"40.748440, -73.984559"}' \
'https://<tenant-env-fqdn>/am/json/realms/root/sessions/?_action=updateSessionProperties'
{
    "LoginLocation": "40.748440, -73.984559"
}

To set multiple properties in a single REST API call, specify the list of properties and their values in the JSON payload; for example:

--data '{"property1":"value1", "property2":"value2"}'

To set the value of a session property on another user’s session, specify the session token of the user performing the action in the <session-cookie-name> header and the session token to be modified as the value of the tokenId:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"LoginLocation": "40.748440, -73.984559", "tokenId": "BXCCq…​NX*1*"}' \
'https://<tenant-env-fqdn>/am/json/realms/root/sessions/?_action=updateSessionProperties'
{
    "LoginLocation": "40.748440, -73.984559"
}

If the user attempting to modify the session does not have sufficient access privileges, the preceding examples result in a 403 Forbidden error.

You cannot set properties internal to Identity Cloud sessions. If you try to modify an internal property in a REST API call, Identity Cloud also returns a 403 Forbidden error; for example:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQICS…​NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"AuthLevel":"5", "tokenId": "BXCCq…​NX*1*"}' \
'https://<tenant-env-fqdn>/am/json/realms/root/sessions/?_action=updateSessionProperties'
{
    "code": 403,
    "reason": "Forbidden",
    "message": "Forbidden"
}

For a list of the default session properties, refer to Session properties.

Copyright © 2010-2023 ForgeRock, all rights reserved.