PingOne Platform APIs

Client-Initiated Backchannel Authentication

The Client-Initiated Backchannel Authentication (CIBA) flow is an OpenID Connect specification. Learn more in CIBA grant type.

Applications must be configured with a grantTypes value of ciba and a tokenEndpointAuthMethod value of CLIENT_SECRET_BASIC, CLIENT_SECRET_JWT, PRIVATE_KEY_JWT, or CLIENT_SECRET_POST.

PingOne supports the following CIBA endpoints:

  • POST /{{envID}}/as/cibaAuthorization begins the CIBA flow. The application includes the user identifier in the request body and the endpoint returns an auth_req_id value.

    The application must include a value for either login_hint, id_token_hint, or login_hint_token in the request body. Providing more than one of these properties will result in an error.

  • POST /{{envID}}/as/token returns tokens to the application. The application polls this endpoint with the auth_req_id value until it succeeds or reaches a terminal state.

CIBA data model

Property Type Required? Mutable? Description

client_id

String

Required

Mutable

Required when the application’s tokenEndpointAuthMethod is CLIENT_SECRET_POST. The application’s ID.

client_secret

String

Required

Mutable

Required when the application’s tokenEndpointAuthMethod is CLIENT_SECRET_POST. The application’s client secret.

client_assertion

String

Required

Mutable

Required when the application’s tokenEndpointAuthMethod is CLIENT_SECRET_JWT or PRIVATE_KEY_JWT. A signed JWT used to authenticate the client.

client_assertion_type

String

Required

Immutable

Required when the application’s tokenEndpointAuthMethod is CLIENT_SECRET_JWT or PRIVATE_KEY_JWT. Must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

request

String

Optional

Mutable

Signed authentication request made by encoding all of the authentication request parameters as claims of a signed JWT with each parameter name as the claim name and its value as a JSON string. Must contain the following RFC7519 registered claims: aud, iss, exp, iat, nbf, jti.

acr_values

String

Optional

Mutable

DaVinci policy ID which handles the end user authentication device. It has to be a "P1" type flow with "CIBA" subtype. If no value is provided then the first P1 type flow with CIBA subtype is used.

scope

String

Required

Mutable

The openid scope is required. If the offline_access scope is provided and the application configuration has refresh tokens enabled, then a successful token response will include a refresh token.

binding_message

String

Optional

Mutable

Message intended to be displayed on both the consumption device and the authentication device. The value must be at least 1 character in length and at most 8 characters. The set of allowed characters is [A-Za-z0123456789_-].

requested_expiry

String or Integer

Optional

Mutable

The expires_in value in seconds for the auth_req_id the endpoint will return. The default value is 120 seconds, with a maximum of 300.

login_hint

String

Required

Mutable

The application provides a string that PingOne can map to a user, such as a username or email address.

id_token_hint

String

Required

Mutable

The application provides an ID token representing a previous authentication for the target user. This ID token must have been issued by PingOne.

login_hint_token

String

Required

Mutable

The application provides a JWT containing the user ID as a claim. This token is created and signed by the application.

Response codes

While the application polls the token endpoint, it may receive the following responses:

Response message Description

authorization_pending

The user has not yet authenticated.

slow_down

A variant of authorization_pending, where the user has not yet authenticated, but the client must increase the polling interval by 5 seconds for subsequent requests.

access_denied

The user denied or failed the authentication request.

expired_token

The auth_req_id value has expired.

invalid_grant

The auth_req_id value is invalid or has already been used.

invalid_request

The client provided a non-CIBA grant type.

invalid_client

The client provided bad credentials.

unauthorized_client

The client is not registered to use the CIBA grant type.