PingOne Platform APIs

CIBA grant type

The Client-Initiated Backchannel Authentication (CIBA) flow is an OpenID Connect specification. CIBA involves a consumption device, on which the user interacts with the relying party (RP), and an authentication device, on which the user authenticates with the OpenID Provider and grants consent.

The CIBA specification defines three token delivery modes: poll, ping, and push. PingOne currently only supports poll mode, specifically only standard polling, not long polling.

Consider a typical CIBA flow where:

  1. An end uses selects $50 on a gas pump (the consumption device).

  2. The point-of-sale application (the RP) sends a request to PingOne (the OpenID Provider).

  3. PingOne invokes a PingOne MFA integration or DaVinci flow to prompt the user’s device (the authentication device), such as their smartphone.

  4. The user approves the transaction on their device.

The application 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.

CIBA authorization endpoint

First, the application initiates the CIBA flow with the POST /{{envID}}/as/cibaAuthorization endpoint. In the body of this auth request, the application identifies the target end user with one of three properties:

login_hint

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

id_token_hint

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

The application provides a JWT containing the user ID as a claim. This token is created and signed by the application. Learn more in Create a login_hint_token JWT.

Providing more than one of these properties will result in an error.

The auth endpoint returns an auth_req_id value that the application then sends to the POST /{{envID}}/as/token to receive an access token and ID token.

Token endpoint

Next, the application polls the POST /{{envID}}/as/token endpoint for tokens. The request body must include the auth_req_id value returned from the CIBA authorization endpoint, and the grant_type value of urn:openid:params:grant-type:ciba.

Using the poll token delivery method, the application continues to poll this endpoint until it receives a success response or an error response indicating a terminal state.

Once the user approves the request on their authentication device, PingOne returns a successful token response with an access token and ID token.

Response codes

If the user has not yet responded to the authentication request, PingOne returns the following token response:

{
    "error": "authorization_pending",
    "error_description": "The request could not be completed. There was an issue processing the request.: The authorization request is still pending. (Correlation ID: <id>)"
}

If the application on the consumption device sends its token request too frequently, PingOne returns the following token response:

{
    "error": "slow_down",
    "error_description": "The request could not be completed. There was an issue processing the request.: The authorization request is still pending. Please slow down the poll requests. (Correlation ID: <id>)"
}

If the user declines the request, PingOne returns the following token response:

{
    "error": "access_denied",
    "error_description": "The request could not be completed. There was an issue processing the request.: The authorization request has been denied. (Correlation ID: <id>)"
}

If the CIBA request has expired, PingOne returns the following token response:

{
    "error": "expired_token",
    "error_description": "The request could not be completed. There was an issue processing the request.: The authorization request for the provided auth_req_id has expired. (Correlation ID: <id>)"
}