Back-channel authentication endpoint (CIBA)

1. Back-channel authentication request

The CIBA flow enables client applications to submit a back-channel request to authenticate an end-user and obtain their consent. The Connect2id server then typically invokes a native IdP app on a user’s mobile device to let the user authorise the request.

CIBA is specified in OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0.

2. The CIBA endpoint URL

It is advertised in the backchannel_authentication_endpoint server metadata and has this form:

[issuer-url]/ciba

3. Client authentication

Confidential clients must authenticate as they would at the token endpoint.

4. Web API overview

Resources
/ciba [POST]
Representations	Errors
Request Request acknowledgement Error	400 Bad Request 401 Unauthorized 500 Internal Server Error

4. Resources

4.1 /ciba

4.1.1 POST

Submits the CIBA request parameters to obtain an auth_req_id for use at the token endpoint.

Header parameters:

[ Authorization ] Used for HTTP basic authentication of the client.
Content-Type Must be application/x-www-form-urlencoded.
[ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.
[ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Body:

The CIBA request parameters, together with any client authentication parameters.

Success:

Code: 200
Content-Type: application/json
Body: {object} The CIBA request acknowledgement.

Errors:

400 Bad Request with an error code.
401 Unauthorised with an error code.
500 Internal Server Error

Example CIBA request for an ID token, using the email address alice@example.com as login hint and the binding message MO 20 AE. The client authenticates with the private_key_jwt method.

POST /ciba HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

scope=openid
&login_hint=alice%40example.com
&binding_message=MO%20D7%20AE
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.eyJpc3Mi...

Example success response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "auth_req_id" : "uo-EOVpCEZ8kGOQOn4ovDw.MDE3NzM3Y2MtZGEzMy00MDA4LTk3OWItMTJiYzE5YzcwZTVm.Z_Fziw.aVfev4yzxWDq8fQuZhBUqA",
  "expires_in"  : 600
}

5. Representations

5.1 Request

The CIBA request must include either a login_hint_token, an id_token_hint or login_hint that resolves to a subject (end-user) identifier.

Plain request

The request may include additional parameters than the those listed below.

scope Space separated list of the requested scope values. For an OpenID authentication request the scope must include the openid value. May be omitted if a RAR authorization_details parameter is used.
[ acr_values ] Optional space separated list of requested Authentication Context (ACR) Class Reference values.
[ login_hint_token ] A login hint token obtained from the STS endpoint.
[ id_token_hint ] An ID token hint from a previous authentication of the end-user. Its exp (expiration) may be in the past.
[ login_hint ] A login hint that resolves to a subject identifier.
[ binding_message ] Optional binding message to display in the IdP app. It must match the configured binding message pattern.
[ user_code ] Optional user code, such as a pin, known by the end-user, to pre-authorise the CIBA request. Use of this parameter is discouraged, in favour of a login_hint_token.
[ requested_expiry ] Optional positive integer to request a specific expires_in value of the auth_req_id in the request acknowledgement. The Connect2id server will bound the value to the maximum allowed.
[ request_context ] Optional JSON object with details to inform fraud and threat decisions, such as the geolocation of the CIBA consumption device.

Signed request

request A signed JWT containing the CIBA request parameters as claims. The following JWT claims must also be present:
- iss The client_id of the client.
- aud The issuer URL of the Connect2id server.
- exp The JWT expiration time.
- iat The JWT issue time.
- nbf The time before which the JWT must not be used.
- jti Unique JWT identifier.

Example JWT header and claims for a signed CIBA request:

{
  "alg" : "ES256",
  "kid" : "3uUg"
}

{
  "iss"             : "egatai2y",
  "aud"             : "https://c2id.com",
  "exp"             : 1744021480,
  "iat"             : 1743961480,
  "nbf"             : 1743961480,
  "jti"             : "er1Taepa",
  "scope"           : "openid",
  "login_hint"      : "alice@example.com",
  "binding_message" : "MO D7 AE"
}

5.2 Request acknowledgement

JSON object with members:

auth_req_id The request ID to use at the token endpoint.
expires_in The lifetime of the request ID, in seconds.

Example:

{
  "auth_req_id" : "uo-EOVpCEZ8kGOQOn4ovDw.MDE3NzM3Y2MtZGEzMy00MDA4LTk3OWItMTJiYzE5YzcwZTVm.Z_Fziw.aVfev4yzxWDq8fQuZhBUqA",
  "expires_in"  : 600
}

5.3 CIBA error

JSON object with members:

error An error code which can take one of the following values:
- invalid_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
- invalid_client Client authentication failed, due to missing or invalid client credentials.
- unauthorized_client The client is not registered for the CIBA grant.
- invalid_scope The requested scope is invalid, unknown, or malformed.
- expired_login_hint_token The login_hint_token has expired.
- unknown_user_id The hint couldn’t be resolved to a subject (end-user) identifier.
- missing_user_code The client must include a user_code.
- invalid_user_code The user_code is invalid.
- invalid_binding_message The binding_message is not acceptable.
- access_denied The user or the IdP denied the authorisation request.
[ error_description ] Optional text providing additional information about the error that occurred.
[ error_uri ] Optional URI for a web page with information about the error that occurred.

Example CIBA error:

{
  "error"             : "expired_login_hint_token",
  "error_description" : "Expired login_hint_token"
}

6. Errors

400 Bad Request

Invalid request. See PAR error codes for more information.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "expired_login_hint_token",
  "error_description" : "Expired login_hint_token"
}

401 Unauthorized

The request was denied due to an invalid or missing client authentication. See error codes for more information. The error_description is a checklist of all possible causes why the client authentication may have failed. The client_auth_id can be used to identify the exact cause.

Example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error"             : "invalid_client",
  "error_description" : "Invalid client: Possible causes may be missing /
                         invalid client_id, missing client authentication,
                         invalid or expired client secret, invalid or expired
                         JWT authentication, invalid or expired client X.509
                         certificate, or an unexpected client authentication
                         method",
  "client_auth_id"    : "cgXB4EyYViWPt6g2"
}

500 Internal Server Error

An internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error