PingFederate Server

CIBA by ping

The OAuth Client Initiated Backchannel Authentication (CIBA) grant by ping process takes place between the client, user, authentication device, PingFederate, and resource server (RS).

After receiving an authentication request acknowledgment, the client waits for a ping callback message from the OpenID Provider (OP). When the OP receives the authorization granted by the user through the authentication device, it sends a ping callback message to the client’s notification endpoint. The client then sends a token request to retrieve an access token.

Flowchart depicting the CIBA by poll process between the Client, User, Authentication Device, AS/OP and RS.
OAuth CIBA grant by ping

Processing steps

  1. The client sends an authentication request to PingFederate at its client-initiated backchannel authentication endpoint.

    The client must include in its authentication request the desired scope of permissions, one identity hint for PingFederate to identify the user, and a bearer token that PingFederate can use to authenticate the ping callback message. When providing an identity hint, the client has three options:

    • login_hint

    • login_hint_token

    • id_token_hint

    For the bearer token, the client must follow the syntax as defined in .ietf.org/html/rfc6750//[RFC 6750, section 2.1] and transmit it using the client_notification_token parameter.

    The client can include a user code using the user_code parameter, transmit all request parameters of the authentication request in a signed request object, or do both.

    The authentication request can be signed or unsigned.

  2. PingFederate validates the authentication request and identifies the user based on the hint provided by the client.

  3. PingFederate returns an authentication request acknowledgment to the client. The response contains the identifier, auth_req_id, that PingFederate assigns to the authentication request.

  4. PingFederate invokes a CIBA authenticator based on the applicable CIBA request policy to reach out to the user with the information (for example, the requested scopes) that the user needs to obtain authorization.

  5. The authentication device presents the information and works with the user to obtain authorization.

  6. The user reviews the information presented by the authentication device and then approves or denies the scopes requested by the client.

  7. The authentication device sends the authorization result back to PingFederate.

  8. PingFederate sends a ping callback message using the HTTP POST method to the client at its notification endpoint.

    Per specification, PingFederate includes the client_notification_token value in the Authorization HTTP request header and the auth_req_id value in the message body.

  9. The client sends a token request to PingFederate at its token endpoint.

    The client must include in its token request the CIBA grant type, urn:openid:params:grant-type:ciba, and the corresponding auth_req_id value.

  10. PingFederate returns an access token in a token response to the client.

    If the user denies the requested scopes, PingFederate provides the client with a relevant error message in the token response.

  11. The client provides the access token to the RS to access protected resources.

  12. The RS validates the access token.

  13. The RS provides the requested data to the client.