PingAM 7.5.0

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.

The type of tokenId returned varies depending on where AM stores the sessions for the realm to which the user authenticates:

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

  • If client-side sessions are enabled, the tokenId object is the session state for that particular user or identity.

Developers should be aware that the size of the tokenId for client-side sessions—2000 bytes or greater—is considerably longer than for server-side sessions—approximately 100 bytes. For more information about session tokens, see Session cookies and session security.

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://openam.example.com:8443/openam/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 "iPlanetDirectoryPro: 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 iPlanetDirectoryPro. This header field name must correspond to the name of the AM session cookie—by default, iPlanetDirectoryPro. You can find the cookie name in the AM admin UI, by navigating to Deployment > Servers > Server Name > Security > Cookie, in the Cookie Name field of the AM admin UI.

    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 are required to have appropriate privileges in order to access AM functionality using the REST API. For example, users who lack administrative privileges cannot create AM realms. For more information on the AM privilege model, see Delegating Privileges.

  3. Call the REST API to log the user out of AM, as described in Authenticate over 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.