Identity Cloud

Session tokens after authentication

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

If server-side sessions are enabled, the tokenId 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.

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

    $ curl \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'X-OpenAM-Username: bjensen' \
    --header 'X-OpenAM-Password: Secret12!' \
    --header 'Accept-API-Version: resource=2.0, protocol=1.0' \
    'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
    {
        "tokenId":"AQIC5wM…​TU3OQ*",
        "successUrl": "/enduser/?realm=/alpha",
        "realm":"/alpha"
    }

    The returned tokenID is called a session token (also referred to as an SSO token). Each REST API call made after successful authentication 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 authenticated 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, refer to How do I view the tenant session cookie name?

    Once a user has authenticated, you do not need 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. Use the REST API to log the user out of AM, as described in Log out of AM 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.