Authenticate using REST

To authenticate using REST, send an HTTP POST request to the json/authenticate endpoint. You must specify the realm hierarchy. Prefix each realm in the hierarchy with the realms/ keyword; for example, /realms/root/realms/alpha.

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

By default, you authenticate using the default authentication service configured for the realm. To override the default, specify authentication services and other options in the REST request.

PingOne Advanced Identity Cloud supports simple authentication methods, such as providing a username and password, and complex authentication journeys that might involve nested journey evaluations and multi-factor authentication.

For authentication journeys where providing a username and password is sufficient, you can log in by providing these credentials in headers. The following command logs in user bjensen with password Secret12!:

$ 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"
}

This zero page login mechanism works only for username/password authentication.

Note that the POST body is empty. If you submit a POST body, PingOne Advanced Identity Cloud interprets the body as a continuation of an existing authentication attempt that uses a supported callback mechanism. Callback mechanisms support complex authentication journeys, such as those where the user must be redirected to a third party or interact with a device as part of multi-factor authentication.

After successful authentication, PingOne Advanced Identity Cloud returns a tokenId that applications can present as a cookie value for other operations that require authentication. The tokenId is known as the session token. For information about how applications can use session tokens, refer to Session tokens after authentication.

If HttpOnly cookies are enabled, and a client makes a call to the /json/authenticate endpoint with a valid SSO token, PingOne Advanced Identity Cloud returns the tokenId field empty. For example:

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

To authenticate a user without providing them with a session, use the noSession parameter. For details, refer to Authenticate endpoint parameters.

UTF-8 usernames and passwords

To use UTF-8 usernames and passwords in calls to the /json/authenticate endpoint, base64-encode the string, then 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 Åström, follow these steps:

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

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?w4VzdHLDtm0=?=' \
--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": "DDZUA0Ellb4bOt...AIwMQ..*",
  "successUrl": "/enduser/?realm=/alpha",
  "realm": "/alpha"
}

Authenticate to specific authentication services

You can provide PingOne Advanced Identity Cloud with additional information about how a user is authenticating. For example, you can specify a particular authentication journey, or request a list of the authentication services that would satisfy an authentication condition.

The following example specifies the Login journey by using the authIndexType and authIndexValue parameters:

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

You can replace the Login journey with any other journey configured in the realm.

For details about using the authIndexType parameter to authenticate to specific services, refer to Authenticate endpoint parameters.

The /json/authenticate endpoint supports callback mechanisms to perform complex authentication journeys. When PingOne 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.

The following callback types are available:

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 PingOne 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 PingOne 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, PingOne Advanced Identity Cloud may return several callbacks sequentially. Each must be completed and returned to PingOne Advanced Identity Cloud until authentication is successful.

The following example shows a request for authentication, and PingOne 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 PingOne Advanced Identity Cloud.
2	The type of callback. It must be listed under Supported callbacks.
3	The information PingOne Advanced Identity Cloud offers about this callback. Usually, this information would be displayed to the user in the UI.
4	The information PingOne 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://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
  "tokenId": "lWY23F4fuC7cu4Fq4GQa5u6drlQ...*",
  "successUrl": "/enduser/?realm=/alpha",
  "realm": "/alpha"
}

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

For details about the callbacks PingOne Advanced Identity Cloud can return, refer to Supported callbacks.

PingOne Advanced Identity Cloud

Authenticate using REST

UTF-8 usernames and passwords

Authenticate to specific authentication services

Return callback information