PingOne Advanced Identity Cloud

Backchannel authentication

Backchannel authentication lets a third-party federation service initiate authentication with PingOne Advanced Identity Cloud on behalf of a user. The federation service collects the user data and transmits this data directly to PingOne Advanced Identity Cloud. PingOne Advanced Identity Cloud redirects the user to complete the authentication process without having to re-enter the collected data. Backchannel authentication provides a seamless user experience and is more secure as users don’t have to enter credentials multiple times.

Backchannel authentication uses a transactional authorization process with requests sent to the backchannel authentication REST endpoints. Data supplied by the federation service is saved in a transaction with a specific transaction ID. When the user starts their authentication journey in PingOne Advanced Identity Cloud, the transaction locates the federation-provided data and inserts it into the journey’s shared state.

The following diagram illustrates the backchannel authentication flow.

backchannel-auth

Demonstrate backchannel authentication

These steps use an OAuth 2.0 client to mimic the third-party federation service. The client initializes the backchannel authentication transaction and PingOne Advanced Identity Cloud redirects the user to a simple login journey to complete authentication.

The process includes the following steps:

  1. Create an authentication journey

  2. Configure the OAuth 2.0 provider service

  3. Create an OAuth 2.0 client

  4. Configure the Base URL Source

  5. Allowlist session properties (optional)

  6. Get an access token

  7. Initialize the backchannel authentication transaction

  8. Complete the backchannel authentication

  9. Check the status of the backchannel authentication request

Create an authentication journey

This example assumes a simple journey that lets the user log in by supplying only their password. The username is provided by the third-party federation service as part of the backchannel authentication request.

The name of the journey is Login.

backchannel auth journey

Configure the OAuth 2.0 provider service

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced.

  2. In the Client Registration Scope Allowlist field, add back_channel_authentication and click Save.

  3. In the Grant Types field, add Client Credentials if it isn’t already there.

Find more information in Authorization server configuration.

Create an OAuth 2.0 client

The OAuth 2.0 client represents the third-party federation service.

Create a confidential client named myClient with the following configuration:

  • Client ID: myClient

  • Client secret: my-client-secret

  • Scope(s): back_channel_authentication

  • Grant Types: Client Credentials

Find more information in Client application registration.

Configure the Base URL Source

By default, the base URL of the redirect URI is retrieved from the incoming HTTP request. For this demonstration, configure a fixed base URL with the value of your PingOne Advanced Identity Cloud host.

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Services and click Add a Service.

  2. Select Base URL Source and click Create.

  3. In the Base URL Source list, select Fixed value.

  4. Set the Fixed value base URL to your PingOne Advanced Identity Cloud host, for example, https://[.var]##<tenant-env-fqdn>##/am.

  5. Click Save Changes.

Allowlist session properties (optional)

When you query the state of a successful backchannel authentication, you might want to obtain certain session details. To do this, configure the Session Property Whitelist Service and specify any properties to be included in a query response.

  1. Go to Realms > Realm Name > Services, and click Add a Service.

  2. Select Session Property Whitelist Service and click Create.

  3. In the Allowlisted Session Property Names, enter the session properties you want to obtain.

  4. Click Save Changes.

Get an access token

Get an access token with a scope of back_channel_authentication using the client credentials grant. For example:

$ curl \
--request POST \
--data "grant_type=client_credentials" \
--data "client_id=myClient" \
--data "client_secret=my-client-secret" \
--data "scope=back_channel_authentication" \
"https://[.var]##<tenant-env-fqdn>##/am/oauth2/realms/root/realms/alpha/access_token"
{
  "access_token": "FnpG1lU0fUooJFY-82sq3UiAnGA",
  "scope": "back_channel_authentication",
  "token_type": "Bearer",
  "expires_in": 3599
}

Find more information in Client application authentication.

Initialize the backchannel authentication transaction

This section assumes that a user has already signed on to the third-party federation service and that the service has their username.

As the OAuth 2.0 client, send an HTTP POST request to the /authenticate/backchannel/initialize endpoint. Specify the authentication journey to which the user should be redirected and the username in the JSON payload.

Optionally, specify a custom tracking ID that lets the federation service track the request through PingOne Advanced Identity Cloud. If provided, PingOne Advanced Identity Cloud logs this ID and its own audit tracking ID. The custom tracking ID must be a string of 36 characters or less and can include only the characters A-Z a-z 0-9 - and _.

For example:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1, protocol=2.0" \
--header "Authorization: Bearer FnpG1lU0fUooJFY-82sq3UiAnGA" \
--data '{
  "type": "Service",
  "value": "Login",
  "subject": {
    "type": "user",
    "name": "bjensen"
  },
  "trackingId": "Y5tyzQi9cGVJjy2L"
}' \
"https://[.var]##<tenant-env-fqdn>##/am/json/realms/root/realms/alpha/authenticate/backchannel/initialize"
{
  "transaction": "b3070138-cd73-4ef2-bd58-812602d7b757",
  "redirectUri": "https://[.var]##<tenant-env-fqdn>##/am/XUI/Login?realm=/alpha&authIndexType=transaction&authIndexValue=b3070138-cd73-4ef2-bd58-812602d7b757"
}

PingOne Advanced Identity Cloud returns a transaction ID and the complete redirect URI, including the transaction ID.

Complete the backchannel authentication

In a real-world scenario, the user follows the redirectUri provided in the response and completes the authentication.

As user bjensen, open the provided redirect URI in a browser window:

backchannel login

Enter bjensen’s password. Her username was provided in the backchannel initiation request.

Click Next and observe that bjensen is authenticated.

Check the status of the backchannel authentication request

Using the same access token, send an HTTP POST request to the /authenticate/backchannel/info endpoint, specifying the transaction ID in the JSON payload. For example:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1, protocol=2.0" \
--header "Authorization: Bearer Nc_SMVZ85VTJ_CDpaqO5JkMBOAs" \
--data '{
    "transaction": "b3070138-cd73-4ef2-bd58-812602d7b757"
}' \
"https://[.var]##<tenant-env-fqdn>##/am/json/realms/root/realms/alpha/authenticate/backchannel/info"
{
  "state": "COMPLETED",
  "result": "APPROVED",
  "auditTrackingIds": [
    "82d76902-7d18-41ea-9ae6-05643b05d018-1029776",
    "trackingId": "Y5tyzQi9cGVJjy2L"
  ],
  "type": "service",
  "value": "Login",
  "subject": {
    "type": "user",
    "name": "bjensen"
  },
  "sessionProperties": {
    "authInstant": "2024-12-03T14:04:31Z"
    "AMCtxId": "1289ff8c-c712-9215-b282-bad671f56vy2-847363"
    "Service": "Login"
  }
}

The response includes the following:

  • The state of the transaction (CREATED, IN_PROGRESS, or COMPLETED)

  • The result of the backchannel authentication (UNKNOWN, APPROVED, or DENIED)

  • An array of auditTrackingIds, including the standard audit ID PingOne Advanced Identity Cloud generates and any custom tracking IDs supplied in the initial request.

  • Any allowlisted sessionProperties.

Backchannel authentication REST endpoints

PingOne Advanced Identity Cloud exposes the following REST endpoints for backchannel authentication:

Endpoint Description

/authenticate/backchannel/initialize

Lets a third-party federation service initiate a backchannel authentication flow.

/authenticate/backchannel/info

Lets a third-party federation service verify that a backchannel authentication process completed successfully.

You must access this endpoint with an OAuth 2.0 token that has the back_channel_authentication scope. The token must have been granted by the same PingOne Advanced Identity Cloud tenant specified in the redirect URI.

Find reference information on these endpoints in json/authenticate/backchannel.