The client-initiated backchannel authentication endpoint is defined in the OpenID Connect Client Initiated Backchannel Authentication Flow specification (openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html). A CIBA-capable client uses this endpoint to initiate a backchannel, out-of-band flow to authenticate the resource owners and to obtain their authorizations.
Per specification, 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. This is a required parameter. Important:
When sending request parameters of an authentication request via a signed request object, the client must include the client_id parameter (and its value) inside and outside of the request parameter value. Furthermore, 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 screen. Scopes can also be constrained on a client-to-client basis.This is a required parameter.
Additionally, it must include the |
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 in RFC
6750 (tools.ietf.org/html/rfc6750#section-2.1). Required only if the client is configured to use the poll delivery method. |
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.
|
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.
Required only if the client record is configured to support user code and associated with a user code-enabled CIBA request policy. |
binding_message | An alphanumeric message intended to be made available on both the
authentication device and the consumption device so that the user can tie
them together and decide whether to grant the requested authorization.
When provided, the length of the message must range from 1 through 20. |
requested_expiry | The requested expiration time of the request in seconds since the
generation of the authentication request acknowledgment. Note:
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. Required if the client is configured to transmit request parameters to the backchannel authentication endpoint in signed request objects. (In other words, the Require CIBA Signed Requests check box 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. Optional if a client is not 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 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 algorithm (or algorithms). If the signature does not pass the verification process, the request fails. Important:
In the scenario where 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; for example:
HTTP/1.1 200 OK ... { "auth_req_id": "HQnCgSeUzWNORZEv8n3E8wIip9L3iwBdJAAect04BqdpEsFBGqfxRvoa_Q", "interval": 3, "expires_in": 120 }
- 400 - Bad Request; for example:
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; for example:
HTTP/1.1 401 Unauthorized ... { "error_description": "Invalid client or client credentials.", "error": "invalid_client" }
- 500 - Server Error; for example:
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, refer to section 13. Authentication Error Response in the specification (openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#rfc.section.13).
- 200 - Success; for example:
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. Alternatively, clients can provide credentials using these request parameters: client_id and client_secret. Important:
This is a sensitive parameter. To avoid recording it in web server logs, we recommend to only pass in this parameter (via the HTTP POST method) in the message body or through the use of the HTTP Basic authentication scheme, instead of in a query string. |
Client certificate | Clients must present their client certificate for mutual TLS authentication. The issuer and the subject DN of the client certificate must match values configured for the clients. |
Private key JWT | Clients must include request parameters
client_assertion_type and
client_assertion in the message body of their requests.
Example:
Note:
For readability, line breaks are inserted and the authentication token is truncated. For more information about the private_key_jwt client authentication method, see Client Authentication in the OpenID Connect specification (openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) and Using Assertions for Client Authentication in RFC7521 (tools.ietf.org/html/rfc7521#section-4.2). |
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) 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. Note:
When the access_token_manager_id parameter is specified, PingFederate ignores the aud 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. |
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 which would be 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 1: 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
- Example 2: An exact match is a better match than a partial match
-
Access Token Management instances Resource URIs (configured) ATM1 https://localhost:9031/app1
https://localhost:9031/app2/data
https://app.example.local
ATM2 https://localhost:9031/app1/data
https://localhost:9031/app2/data/get
https://localhost:9031/app1
(a resource URI pre-configured for ATM1) is a partial match for https://localhost:9031/app1/data (the provided URI). However, ATM2 is chosen becausehttps://localhost:9031/app1/data
(a resource URI pre-configured for ATM2) is an exact match against the provided URI. - Example 3: A more specific partial match is a better match
- Both
https://localhost:9031/app2/data
(a resource URI for ATM1) andhttps://localhost:9031/app2/data/get
(a resource URI for ATM2) are partial matches for https://localhost:9031/app2/data/get/sample (the provided URI). However, ATM2 is chosen becausehttps://localhost:9031/app2/data/get
matches more specifically against the provided URI.