Return callback information

The /json/authenticate endpoint supports callback mechanisms to perform complex authentication journeys. When Advanced Identity Cloud needs to return or request information, it returns a JSON object with the authentication step, the authentication identifier, and the related callbacks.

Advanced Identity Cloud supports the following callback types:

Read-only callbacks: Read-only callbacks provide information to the user, such as text messages or the period of time a user must wait before continuing their authentication journey.
Interactive callbacks: Interactive callbacks request information from the user. For example, their username and password, or a request that they select between different configured options.
Backchannel callbacks: Backchannel callbacks let Advanced Identity Cloud access additional information from the user’s request. For example, a specific header or certificate.

Read-only and interactive callbacks have an array of output elements that can be displayed to the end user. The JSON returned in an interactive callback includes an array of input elements that must be completed and returned to Advanced Identity Cloud. 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, Advanced Identity Cloud could return several callbacks sequentially. Each must be completed and returned to Advanced Identity Cloud until authentication is successful.

Example callback

The following example shows a request for authentication, and Advanced Identity Cloud’s response with the NameCallback and PasswordCallback:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'

{
  "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ...", (1)
  "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 Advanced Identity Cloud.
2	The type of callback. It must be listed under Return callback information.
3	The information Advanced Identity Cloud offers about this callback. Usually, this information would be displayed to the user in the UI.
4	The information Advanced Identity Cloud is requesting. The user must complete the `"value": ""` field with the required information.

To respond to a callback, send back the whole JSON object, including the missing values. The following example shows how to respond to the NameCallback and PasswordCallback callbacks, returning the username (bjensen) and the password (Secret12!):

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--data '{
  "authId":""eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ...",
  "callbacks": [
    {
      "type": "NameCallback",
      "output": [
        {
          "name": "prompt",
          "value": "User Name"
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": "bjensen"
        }
      ],
      "id": 0
    },
    {
      "type": "PasswordCallback",
      "output": [
        {
          "name": "prompt",
          "value": "Password"
        }
      ],
      "input": [
        {
          "name": "IDToken2",
          "value": "Secret12!"
        }
      ],
      "_id": 1
    }
  ],
}' \
'https://[.var]<tenant-env-fqdn>_/am/json/realms/root/realms/alpha/authenticate'
{
  "tokenId": "lWY23F4fuC7cu4Fq4GQa5u6drlQ...*",
  "successUrl": "/enduser/?realm=/alpha",
  "realm": "/alpha"
}

In complex authentication journeys, Advanced Identity Cloud could send several callbacks sequentially. Each must be completed and returned to Advanced Identity Cloud until authentication is successful.

PingOne Advanced Identity Cloud

Return callback information

Example callback