Managing Sessions (REST)

AM provides REST APIs under /json/sessions for the following use cases:

Obtaining Information About Sessions Using REST

To get information about a session, send an HTTP POST to the /json/sessions/ endpoint, using the getSessionInfo action. This endpoint returns information about the session token provided in the iPlanetDirectoryPro header by default. To get information about a different session token, include it in the POST body as the value of the tokenId parameter.

Note

For information about how to retrieve custom session properties:

The following example shows an administrative user passing their session token in the iPlanetDirectoryPro header, and the session token of the demo user as the tokenId parameter: 

$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQICS...NzEz*" \
--header "Accept-API-Version: resource=4.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": "BXCCq...NX*1*" }' \
https://openam.example.com:8443/openam/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 CTS-based session and also reset the idle timeout (you cannot reset the idle timeout of client-based sessions), use the getSessionInfoAndResetIdleTime endpoint, as follows: 

$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQICS...NzEz*" \
--header "Accept-API-Version: resource=4.0, protocol=1.0" \
--header "Content-type: application/json" \
--data '{ "tokenId": "BXCCq...NX*1*" }' \
https://openam.example.com:8443/openam/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"
    }
}

Note

To return the AMCtxId property in the session query response as in this example, you must set AMCtxId in the Session Properties to return to session queries setting, under Realms > Realm Name > Services > Session Property Whitelist Service.

Validating Sessions Using REST

To check over REST whether a session token is valid, perform an HTTP POST to the /json/sessions/ endpoint using the validate action. Provide the session token in the POST data as the value of the tokenId parameter. You must also provide the session token of an administrative user in the iPlanetDirectoryPro header.

If you don't specify the tokenId parameter, the session in the iPlanetDirectoryPro header is validated instead.

The following example shows an administrative user, such as amAdmin, validating a session token for the demo user: 

$ curl \
--request POST \
--header "Content-type: application/json" \
--header "iPlanetDirectoryPro: AQICS...NzEz*" \
--header "Accept-API-Version: resource=2.1, protocol=1.0" \
--data '{ "tokenId": "BXCCq...NX*1*" }' \
https://openam.example.com:8443/openam/json/realms/root/sessions?_action=validate

If the session token is valid, the user ID and its realm is returned, as shown below: 

{
  "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 token store. To avoid this, perform a call using the validate&refresh=false action.

Refreshing CTS-Based Sessions Using REST

To reset the idle time of a CTS-based session using REST, perform an HTTP POST to the /json/sessions/ endpoint, using the refresh action. The endpoint will refresh the session token provided in the iPlanetDirectoryPro header by default. To refresh a different session token, include it in the POST body as the value of the tokenId query parameter.

The following example shows an administrative user passing their session token in the iPlanetDirectoryPro header, and the session token of the demo user as the tokenId parameter: 

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header "iPlanetDirectoryPro: AQICS...NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{ "tokenId": "BXCCq...NX*1*" }' \
https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=refresh
{
  "uid": "demo",
  "realm": "/",
  "idletime": 17,
  "maxidletime": 30,
  "maxsessiontime": 120,
  "maxtime": 7106
}

On success, AM resets the idle time for the CTS-based session, and returns timeout details of the session.

Resetting a CTS-based session's idle time triggers a write operation to the Core Token Service token store. Therefore, to avoid the overhead of write operations to the token store, be careful to use the refresh action only if you want to reset a CTS-based session's idle time.

Because AM does not monitor idle time for client-based sessions, do not use the tokenId of a client-based session when refreshing a session's idle time.

Invalidating Sessions Using REST

To invalidate a session, perform an HTTP POST to the /json/sessions/ endpoint using the logout action. The endpoint will invalidate the session token provided in the iPlanetDirectoryPro header: 

$ curl \
--request POST \
--header "Content-type: application/json" \
--header "iPlanetDirectoryPro: AQICS...NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=logout
{
    "result": "Successfully logged out"
}

On success, AM invalidates the session and returns a success message.

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

{
  "result": "Token has expired"
}

To invalidate a different session token, include it in the POST body as the value of the tokenId parameter.

For example, the following command shows an administrative user passing their session token in the iPlanetDirectoryPro header, and the session token of the demo user as the tokenId parameter: 

$ curl \
--request POST \
--header "Content-type: application/json" \
--header "iPlanetDirectoryPro: AQICS...NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{ "tokenId": "BXCCq...NX*1*" }' \
"https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=logout"
{
    "result": "Successfully logged out"
}

Getting and Setting Session Properties Using REST

AM lets you read and update properties on users' sessions using REST API calls.

Before you can perform operations on session properties using the REST API, you must first define the properties you want to set in the Session Property Whitelist Service configuration. For information on whitelisting session properties, see "Session Property Whitelist Service".

You can use REST API calls for the following purposes:

  • To retrieve 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.

  • To read property values.

  • To update property values.

Session state affects the ability to set and delete properties as follows:

  • You can set and delete properties on a CTS-based session at any time during the session's lifetime.

  • You can only set and update properties on a client-based session during the authentication process, before the user receives the session token from AM. For example, you could set or delete properties on a client-based session from within a post-authentication plugin.

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

  • Specify the session token of the user performing the operation on session properties in the iPlanetDirectoryPro 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 configuration.

To retrieve the names of the properties you can get or set, and their values, perform an an HTTP POST to the sessions endpoint, /json/sessions/, using the getSessionProperties action, as shown in the following example: 

$ curl \
--request POST \
--header "Content-type: application/json" \
--header "iPlanetDirectoryPro: AQICS...NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{ "tokenId": "BXCCq...NX*1*" }' \
https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=getSessionProperties
{
    "LoginLocation": ""
}

To set the value of a session property, perform an HTTP POST to the sessions endpoint, /json/sessions/, using the updateSessionProperties action. If no tokenId parameter is present in the body of the REST API call, the session affected by the operation is the session specified in the iPlanetDirectoryPro header, as follows: 

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQICS...NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"LoginLocation":"40.748440, -73.984559"}' \
https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=updateSessionProperties
{
    "LoginLocation": "40.748440, -73.984559"
}

You can set multiple properties in a single REST API call by specifying a set of fields and their values in the JSON data. 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 updateSessionProperties action in the iPlanetDirectoryPro, and specify the session token to be modified in the POST body as the value of the tokenId parameter: 

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQICS...NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"LoginLocation": "40.748440, -73.984559", "tokenId": "BXCCq...NX*1*"}' \
https://openam.example.com:8443/openam/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 AM sessions. If you try to modify an internal property in a REST API call, a 403 Forbidden error is returned. For example: 

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQICS...NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"AuthLevel":"5", "tokenId": "BXCCq...NX*1*"}' \
https://openam.example.com:8443/openam/json/realms/root/sessions/?_action=updateSessionProperties
{
    "code": 403,
    "reason": "Forbidden",
    "message": "Forbidden"
}
Read a different version of :