Identity Cloud

Using the session token after authentication

After a successful authentication, AM returns a tokenId object that applications can present as a cookie value for other operations that require authentication. This object is a session token—a representation of the exchange of information and credentials between AM and the user or identity.

If CTS-based sessions are enabled, the tokenId object is a reference to the session state stored in the CTS token store.

The following is a common scenario when accessing AM by using REST API calls:

  1. Call the /json/authenticate endpoint to log a user in to AM.

    This REST API call returns a tokenID value, which is used in subsequent REST API calls to identify the user:

    $ curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "X-OpenAM-Username: demo" \
    --header "X-OpenAM-Password: Ch4ng31t" \
    --header "Accept-API-Version: resource=2.0, protocol=1.0" \
    'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'
    {
        "tokenId":"AQIC5wM…​TU3OQ*",
        "successUrl":"/openam/console",
        "realm":"/alpha"
    }

    The returned tokenID is known as a session token (also referred to as an SSO token). REST API calls made after successful authentication to AM must present the session token in the HTTP header as proof of authentication.

  2. Call one or more additional REST APIs on behalf of the logged-in user.

    Each REST API call passes the user’s tokenID back to AM in the HTTP header as proof of previous authentication.

    The following is a partial example of a curl command that inserts the token ID returned from a prior successful AM authentication attempt into the HTTP header:

    $ curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "<session-cookie-name>: AQIC5w…​NTcy*" \
    --header "Accept-API-Version: resource=2.0, protocol=1.0" \
    --data '{
      …​

    Observe that the session token is inserted into a header field named <session-cookie-name>. This header field name must correspond to the name of the tenant session cookie.

    To find the name of the session cookie, see How Do I View the Tenant Session Cookie Name?

    Once a user has authenticated, it is not necessary to insert login credentials in the HTTP header in subsequent REST API calls. Note the absence of X-OpenAM-Username and X-OpenAM-Password headers in the preceding example.

    Users must have appropriate privileges to access AM functionality using the REST API.

  3. Call the REST API to log the user out of AM, as described in Authenticate using REST.

    As with other REST API calls made after a user has authenticated, the REST API call to log out of AM requires the user’s tokenID in the HTTP header.

Copyright © 2010-2022 ForgeRock, all rights reserved.