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 | |
---|---|
Representations | Errors |
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 RARauthorization_details
parameter is used. -
[ claims ] Object specifying names of OpenID claims to request, whether they are voluntary or essential, and whether they are to be delivered at the UserInfo endpoint or in the ID token. The individual claim names may include language tags. If Identity Assurance is enabled supports verified claims. See section 5.5 of OpenID Connect Core 1.0.
-
[ claims_locales ] The preferred OpenID claims locales as language tags, by order of preference, as space separated string. See section 5.2 of OpenID Connect Core 1.0.
-
[ acr_values ] The requested ACR (authentication strength) values, as space separated string. The default value is the
default_acr_values
metadata parameter in the client registration. -
[ 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 theauth_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.
- iss The
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