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: 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": "AQIC5w…NTcy*",
    "successUrl": "/openam/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. For more information about how applications can use the session token, see 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":"/openam/console",
    "realm":"/alpha"
}

You can request AM to authenticate a user without providing them a session by using the noSession parameter. For more information, see Authenticate endpoint parameters.

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:

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

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://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
{
    "tokenId": "AQIC5w…NTcy*",
    "successUrl": "/openam/console",
    "realm":"/alpha"
}

Authenticate to specific authentication services

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 ldapService chain by using the authIndexType and authIndexValue query string parameters:

$ curl \
--request POST \
--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?authIndexType=service&authIndexValue=ldapService'

You can exchange the ldapService chain with any other chain or tree.

For more information about using the authIndexType parameter to authenticate to specific services, see Authenticate endpoint parameters.

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 link:input elements, which 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://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
{
  "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ…", (1)
  "template": "", (2)
  "stage": "DataStore1", (3)
  "callbacks": [
    {
      "type": "NameCallback", (4)
      "output": [ (5)
        {
          "name": "prompt",
          "value": " User Name: "
        }
      ],
      "input": [ (6)
        {
          "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	A template to customize the look of the authentication module, if exists. For more information, see How do I customize the Login page? in the ForgeRock Knowledge Base.
3	The authentication module stage where the authentication journey is at the moment.
4	The type of callback. It must be listed under Supported callbacks.
5	The information AM offers about this callback. Usually, this information would be displayed to the user in the UI.
6	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 demo 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":"demo"
            }
         ]
      },
      {
         "type":"PasswordCallback",
         "output":[
            {
               "name":"prompt",
               "value":" Password: "
            }
         ],
         "input":[
            {
               "name":"IDToken2",
               "value":"Ch4ng31t"
            }
         ]
      }
   ]
}' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC5wM2…U3MTE4NA..*",
    "successUrl": "/openam/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.

For more information about the callbacks AM may return, refer to Supported callbacks.

AM 7.3.1

Log in to AM over REST

UTF-8 usernames

Authenticate to specific authentication services

Return callback information to AM