PingAM 8.0.0

Authenticate over REST

AM provides the /json/authenticate endpoint for authentication, and the /json/sessions endpoint for managing sessions and logging out.

The following table summarizes authentication operations you can perform using REST:

Task Resources

Authenticate to AM

Authenticating to AM means logging in to a specific realm and receiving a session token from AM. Add parameters to the authentication request to provide AM with more information about how you want to authenticate.

Log in to AM over REST

Use the session token

AM provides you with a session token after authenticating to a realm. Use this token in subsequent calls to AM. For example, when using REST calls to create, modify, or delete configuration objects.

Session token after authentication

Log out of AM

Log out your users by sending a logout action to the /json/sessions endpoint.

Log out of AM over REST

Invalidate sessions

Obtain all the sessions for a given user and invalidate them to ensure they are logged out of AM.

Invalidate sessions

Log in to AM over REST

To authenticate to AM using REST, make an HTTP POST request to the json/authenticate endpoint. You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/customers/realms/europe.

The /json/authenticate endpoint doesn’t support the CRUDPAQ verbs and therefore doesn’t technically satisfy REST architectural requirements. The term REST-like describes this endpoint better than REST.

AM uses the default authentication service configured for the realm. You can override the default by specifying authentication services and other options in the REST request.

AM provides both simple authentication methods, such as providing username and password, and complex authentication journeys that may involve a tree with inner tree evaluation and/or multi-factor authentication.

For authentication journeys where providing a username and password is enough, you can log in to AM using a curl command similar to the following:

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

The username and password are sent in headers. This zero page login mechanism works only for name/password authentication.

Note that the POST body is empty; otherwise, AM interprets the body as a continuation of an existing authentication attempt, one that uses a supported callback mechanism. AM implements callback mechanisms to support complex authentication journeys, such as those where the user needs to be redirected to a third party or interact with a device as part of multi-factor 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 known as the session token. Find information about how applications can use the session token in Session token after authentication.

If HttpOnly cookies are enabled and a client calls the /json/authenticate endpoint with a valid SSO token, AM returns the tokenId field empty.

For example:

{
    "tokenId":"",
    "successUrl":"/am/console",
    "realm":"/alpha"
}

You can request AM to authenticate a user without providing them a session by using the noSession parameter. Learn more in Authenticate endpoints.

UTF-8 usernames

To use UTF-8 usernames and passwords in calls to the /json/authenticate endpoint, base64-encode the string, and wrap the string as described in RFC 2047:

encoded-word = "=?" charset "?" encoding "?" encoded-text "?="

For example, to authenticate using a UTF-8 username, such as ɗëɱø, perform the following steps:

  1. Encode the string in base64 format: yZfDq8mxw7g=.

  2. Wrap the base64-encoded string as per RFC 2047: =?UTF-8?B?yZfDq8mxw7g=?=.

  3. Use the result in the X-OpenAM-Username header passed to the authentication endpoint as follows:

    $ curl \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: =?UTF-8?B?yZfDq8mxw7g=?=" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate'
{
    "tokenId": "AQIC5w…​NTcy*",
    "successUrl": "/am/console",
    "realm":"/alpha"
}

Authenticate to specific authentication trees

You can provide AM with additional information about how you are authenticating. For example, you can specify the authentication tree you want to use, or request from AM a list of the authentication services that would satisfy a particular authentication condition.

The following example shows how to specify the Example tree by using the authIndexType and authIndexValue query string parameters:

$ curl \
--request POST \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=Example'

You can exchange Example with any other tree.

Find information about using the authIndexType parameter to authenticate to specific services in Authenticate endpoints.

Return callback information to AM

The /json/authenticate endpoint supports callback mechanisms to perform complex authentication journeys. Whenever AM needs to return or request information, it will return a JSON object with the authentication step, the authentication identifier, and the related callbacks.

The following types of callbacks are available:

Read-only callbacks

AM uses read-only callbacks to provide information to the user, such as text messages or the amount of time that the user needs to wait before continuing their authentication journey.

Interactive callbacks

Interactive callbacks request information from the user. Use these, for example, to request a user’s username and password or to request that the user select between options.

Backchannel callbacks

AM uses backchannel callbacks when it needs to access additional information from the user’s request. For example, when it requires a particular header or a certificate.

Read-only and interactive callbacks have an array of output elements suitable for displaying to the end user. The JSON returned in interactive callbacks also contains an array of input elements that must be completed and returned to AM.

For example:

"output": [
    {
        "name": "prompt",
        "value": " User Name: "
    }
    ],
"input": [
    {
        "name": "IDToken1",
        "value": ""
    }
]

The value of some interactive callbacks can be returned as headers, such as the X-OpenAM-Username and X-OpenAM-Password headers, but most of them must be returned in JSON as a response to the request.

Depending on how complex the authentication journey is, AM may return several callbacks sequentially. Each must be completed and returned to AM until authentication is successful.

The following example shows a request for authentication, and AM’s response of the NameCallback and PasswordCallback callbacks:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate'
{
  "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ…​", (1)
  "template": "",
  "stage": "DataStore1",
  "callbacks": [
    {
      "type": "NameCallback", (2)
      "output": [ (3)
        {
          "name": "prompt",
          "value": " User Name: "
        }
      ],
      "input": [ (4)
        {
          "name": "IDToken1",
          "value": ""
        }
      ]
    },
    {
      "type": "PasswordCallback",
      "output": [
        {
          "name": "prompt",
          "value": " Password: "
        }
      ],
      "input": [
        {
          "name": "IDToken2",
          "value": ""
        }
      ]
    }
  ]
}
1 The JWT that uniquely identifies the authentication context to AM.
2 The type of callback. It must be listed under Supported callbacks.
3 The information AM offers about this callback. Usually, this information is displayed to the user in the UI.
4 The information AM is requesting. The user must fill the "value": "" object with the required information.

To respond to a callback, send back the whole JSON object with the missing values filled. The following example shows how to respond to the NameCallback and PasswordCallback callbacks, with the bjensen and Ch4ng31t values filled:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--data '{
   "authId":""eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ…​",
   "template":"",
   "stage":"DataStore1",
   "callbacks":[
      {
         "type":"NameCallback",
         "output":[
            {
               "name":"prompt",
               "value":" User Name: "
            }
         ],
         "input":[
            {
               "name":"IDToken1",
               "value":"bjensen"
            }
         ]
      },
      {
         "type":"PasswordCallback",
         "output":[
            {
               "name":"prompt",
               "value":" Password: "
            }
         ],
         "input":[
            {
               "name":"IDToken2",
               "value":"Ch4ng31t"
            }
         ]
      }
   ]
}' \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC5wM…​TU3OQ*",
    "successUrl": "/am/console",
    "realm":"/alpha"
}

On complex authentication journeys, AM may send several callbacks sequentially. Each must be completed and returned to AM until authentication is successful.

Find information about the callbacks AM can return in Supported callbacks.