PingFederate Server

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 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 .ietf.org/html/rfc6750//[RFC 6750].

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.

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

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 parameter is optional. include::partial$pf_rc_allowsignedrequestobjectflexibility.adoc[tags=pf_ph_desc_allowSignedRequestObjectFlexibility]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 .net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html//[13. Authentication Error Response] 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

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 client authentication method, 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.

For more information about the private_key_jwt client authentication method, see .net/specs/openid-connect-core-1_0.html//[Client Authentication] and .ietf.org/html/rfc7521//[Using Assertions for Client Authentication].

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.

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

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.

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 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

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

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, PingFederate chooses ATM2 because https://localhost:9031/app1/data (a resource URI pre-configured for ATM2) is an exact match against the provided URI.

A more specific partial match is a better match

Both https://localhost:9031/app2/data (a resource URI for ATM1) and https://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, PingFederate chooses ATM2 because https://localhost:9031/app2/data/get matches more specifically against the provided URI.