Client-initiated backchannel authentication endpoint - PingFederate - 10.0

Endpoint: /as/bc-auth.ciba

The following table describes parameters for this endpoint. The required Content-Type value is application/x-www-form-urlencoded.

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

OAuth client identification and authentication

The authentication requirement of this endpoint depends on the client authentication method configured for the clients.

...
client_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%
3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=
eyJhbGciOiJSUzI1NiIs...LbSWi1YO-TILOd4L7ZCg&
...

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.

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 because https://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) 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, ATM2 is chosen because https://localhost:9031/app2/data/get matches more specifically against the provided URI.