--- title: Client-initiated backchannel authentication endpoint description: A CIBA-capable client uses this endpoint to initiate a backchannel, out-of-band flow to authenticate the resource owners and obtain their authorizations. component: pingfederate version: 13.1 page_id: pingfederate:developers_reference_guide:pf_ciba_endpoint canonical_url: https://docs.pingidentity.com/pingfederate/13.1/developers_reference_guide/pf_ciba_endpoint.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: March 20, 2023 section_ids: endpoint-asbc-auth-ciba: "Endpoint: /as/bc-auth.ciba" oauth-client-identification-and-authentication: OAuth client identification and authentication oauth-access-token-management-parameters: OAuth access token management parameters example: Example example-a-partial-match: Example - A partial match related-links: Related links --- # Client-initiated backchannel authentication endpoint A CIBA-capable client uses this endpoint to initiate a backchannel, out-of-band flow to authenticate the resource owners and obtain their authorizations. The [OpenID Connect Client Initiated Backchannel Authentication Flow](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) defines the client-initiated backchannel authentication (CIBA) endpoint. | | | | - | ------------------------------------------------ | | | This endpoint accepts only the HTTP POST method. | ## Endpoint: /as/bc-auth.ciba The following table describes parameters for this endpoint. The required `Content-Type` value is `application/x-www-form-urlencoded`. | Parameter | Description | | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client_id`(Required) | The client identifier. When sending request parameters of an authentication request with a signed request object, the client must include the client\_id parameter and its value inside and outside of the request parameter value. Both client\_id parameter values must match. | | `scope`(Required) | The scope of the access request. Expressed as a list of space-separated, case-sensitive strings.Scope values are globally defined on the **System > OAuth Settings > Scope Management** window. You can constrain scopes on a client-to-client basis.This parameter must include the `openid` scope value. | | `client_notification_token` | A bearer token provided by the client that PingFederate must include when sending a ping callback message to the client's notification endpoint. This usage must conform to the syntax for bearer credentials as defined in section 2.1 of [RFC 6750](https://tools.ietf.org/html/rfc6750).If the client is configured to use the poll delivery method, this parameter is required. | | `id_token_hint, login_hint_token, or login_hint` | Per the CIBA specification, the client must include one and only one hint for the OpenID Provider to identify the user. The valid hint parameters are `id_token_hint`, `login_hint`, and `login_hint_token`.- `id_token_hint` Use this parameter to include an ID token as a hint for PingFederate to identify the user. This ID token must be unencrypted. It must be a signed ID token. - `login_hint_token` Use this parameter to include a JSON web token (JWT) as a hint for PingFederate to identify the user. The attributes of this token can vary from one use case to another. For more information how PingFederate uses the login hint token, see [Configuring identity hint contract](../administrators_reference_guide/help_cibapolicymanagementtasklet_cibapolicyrequesthintcontractstate.html). - `login_hint` Use this parameter to provide a hint to PingFederate to identify the user. The value can contain an email address, phone number, account number, subject identifier, username, or any attribute that both sides agreed upon. | | `user_code` | A secret code that is known only to the user and verifiable by PingFederate through the use of a Password Credential Validator instance. The purpose of this code is to authorize the transmission of an authentication request to the user's authentication device.If the client record is configured to support user code and associated with a user code-enabled CIBA request policy, this parameter is required. | | `binding_message` | An alphanumeric message intended to be made available on both the authentication device and the consumption device. The user can tie them together and decide whether to grant the authorization.When provided, the length of the message must range from 1 - 20 characters. | | `requested_expiry` | The requested expiration time of the request in seconds since the generation of the authentication request acknowledgment. PingFederate honors the requested expiration time only if the value is shorter than that of the Transaction Lifetime field found in the associated CIBA request policy. | | `request` | A single, self-contained parameter; a signed JWT whose claims represent the request parameters of the authentication request. The OpenID Connect specification calls this JWT a request object. The requirement of this parameter and the processing rules vary depending on whether the client is configured with the **Require CIBA Signed Requests** option.If the client is configured to transmit request parameters to the backchannel authentication endpoint in signed request objects, this parameter is required. In other words, the **Require CIBA Signed Requests** checkbox is selected in the configuration of the client. When PingFederate receives an authentication request with a signed request object, it verifies the digital signature of the signed request object based on the key obtained from the pre-configured JWKS URL (or JWKS) and the selected CIBA request object signing algorithm (or algorithms). If the signature does not pass the verification process, the request fails.If a client isn't configured to transmit request parameters to the backchannel authentication endpoint in signed request objects, but it is configured with a JWKS URL or an actual JWKS, this parameter is optional.This flexibility allows the client to transmit request parameters in signed request objects for some requests and without the use of signed request objects for some other transactions. When PingFederate receives an authentication request with a signed request object, it verifies the digital signature of the signed request object based on the key obtained from the pre-configured JWKS URL (or JWKS) and the selected CIBA request object signing algorithms. If the signature does not pass the verification process, the request fails. If the client is not configured to transmit request parameters to the backchannel authentication endpoint in signed request objects, and not configured with a JWKS URL or an actual JWKS, an authentication request with a signed request object will always fail. | * Sample authentication request ``` POST /as/bc-auth.ciba HTTP/1.1 Content-Type: application/x-www-form-urlencoded Host: www.example.com client_id=myCibaApp&scope=openid&login_hint=joe@example.com ``` * Sample authentication request acknowledgements * 200 - Success ``` HTTP/1.1 200 OK ... { "auth_req_id": "HQnCgSeUzWNORZEv8n3E8wIip9L3iwBdJAAect04BqdpEsFBGqfxRvoa_Q", "interval": 3, "expires_in": 120 } ``` * 400 - Bad Request ``` HTTP/1.1 400 Bad Request ... { "error_description": "CIBA authentication requests MUST contain the openid scope value.", "error": "invalid_scope" } ``` ``` HTTP/1.1 400 Bad Request ... { "error_description": "Authentication request parameters (such as binding_message) MUST NOT be present outside of the JWT when a signed authentication request is used.", "error": "invalid_request" } ``` ``` HTTP/1.1 400 Bad Request ... { "error_description": "Exactly one (not more, not less) of the hint parameters (i.e. 'login_hint_token', 'id_token_hint' or 'login_hint') must be provided.", "error": "invalid_request" } ``` ``` HTTP/1.1 400 Bad Request ... { "error_description": "User could not be sufficiently identified to initiate out-of-band auth", "error": "unknown_user_id" } ``` ``` HTTP/1.1 400 Bad Request ... { "error": "invalid_user_code" } ``` ``` HTTP/1.1 400 Bad Request ... { "error": "missing_user_code" } ``` ``` HTTP/1.1 400 Bad Request ... { "error_description": "Client is not configured to support user code but a user_code was sent in the request.", "error": "invalid_request" } ``` ``` HTTP/1.1 400 Bad Request ... { "error_description": "Policy is set to require a token for the user hint but login_hint was sent.", "error": "invalid_request" } ``` * 401 - Unauthorized ``` HTTP/1.1 401 Unauthorized ... { "error_description": "Invalid client or client credentials.", "error": "invalid_client" } ``` * 500 - Server Error ``` HTTP/1.1 500 Server Error ... { "error_description": "Client is configured to support user code but server policy doesn't have a PCV configured to do the user code checking", "error": "server_error" } ``` For more information about error responses, see section [13. Authentication Error Response](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) in the specification. ## OAuth client identification and authentication The authentication requirement of this endpoint depends on the client authentication method configured for the clients. | Authentication method | Parameters | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Client secret | Clients can present their client identifier and client secret using the HTTP Basic authentication scheme, where the client identifier is the username, and the client secret is the password.Clients can provide credentials using the request parameters `client_id` and `client_secret`. This is a sensitive parameter. To avoid recording it in web server logs, only pass in this parameter with the HTTP POST method in the message body, or through the HTTP Basic authentication scheme. | | Client certificate | Clients must present their client certificate for mutual TLS authentication. The issuer and the subject distinguished name (DN) of the client certificate must match values configured for the clients. | | Private key JWT or Client Secret JWT | Clients must include request parameters `client_assertion_type` and `client_assertion` in the message body of their requests.- `client_assertion_type` The value describes the format of the assertion as defined by the authorization server. For the private\_key\_jwt and client\_secret\_jwt client authentication methods, the value is `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`. - `client_assertion` The value is the authentication token.**Example**``` ... client_assertion_type= urn%3Aietf%3Aparams%3Aoauth% 3Aclient-assertion-type%3Ajwt-bearer& client_assertion= eyJhbGciOiJSUzI1NiIs...LbSWi1YO-TILOd4L7ZCg& ... ``` For readability, line breaks are inserted and the authentication token is truncated.Learn more about the private\_key\_jwt and client\_secret\_jwt client authentication methods in [Client Authentication](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) and [Using Assertions for Client Authentication](https://datatracker.ietf.org/doc/html/rfc7521/#autoid-7). | | None | Clients must pass in the `client_id` parameter in a query string or the message body to identify themselves. | ## OAuth access token management parameters PingFederate supports multiple access token management (ATM) instances. Clients can specify an ATM instance by providing the ATM ID (`access_token_manager_id`) or a resource URI (`aud` or `resource`) in their requests to the PingFederate OAuth AS. | Parameter | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `access_token_manager_id` | The `access_token_manager_id` value is the instance ID of the desired ATM instance. When specified, PingFederate uses the desired ATM instance for the request if it is eligible; otherwise it aborts the request. When the access\_token\_manager\_id parameter is specified, PingFederate ignores the aud and resource parameter. When the aud parameter is specified, PingFederate ignores the resource parameter. | | `aud` | The `aud` is the resource URI the client wants to access. The provided value is matched against resource URIs configured in access token management instances. When a match is found, PingFederate uses the corresponding access token management instance for the request if it is eligible; otherwise it aborts the request. | | `resource` | The `resource` is the resource URI that the wants to access. The provided value is matched against resource URIs configures in access token management instances. When a match is found, PingFederate uses the corresponding access token management instance for the request if it is elligible. Otherwise it aborts the request.If multiple resource parameters are requested, they must match to a single access token management instance. Otherwise PingFederate aborts the request. | A match can be an exact match or a partial match where the provided URI has the same scheme and authority parts and a more specific path contained within the path of the pre-configured resource URI. PingFederate takes an exact match over a partial match. If there are multiple partial matches, PingFederate takes the partial match where the provided URI matches more specifically against the pre-configured resource URI. ## Example ## Example - A partial match A resource URI of `https://app.example.local` is a partial match for the following provided URIs: * https\://app.example.local/file1.ext * https\://app.example.local/path/file2.ext * https\://app.example.local/path/more ## Related links * [Scopes and scope management](../administrators_reference_guide/pf_scopes_and_scope_management.html) * [Configuring OAuth clients](../administrators_reference_guide/pf_configuring_oauth_clients.html) * [Managing CIBA request policies](../administrators_reference_guide/help_cibapoliciesmanagementtasklet_cibapoliciesmanagementstate.html) * [Defining a request policy](../administrators_reference_guide/help_cibapolicymanagementtasklet_cibapolicymanagementstate.html)