--- title: "Complete Backchannel Authentication" method: POST path: "/api/{serviceId}/backchannel/authentication/complete" tags: ["CIBA"] --- # Complete Backchannel Authentication `POST /api/{serviceId}/backchannel/authentication/complete` This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request on the authentication device. ### Description After the implementation of the backchannel authentication endpoint returns JSON containing an `auth\_req\_id` to the client, the authorization server starts a background process that communicates with the authentication device of the end-user. On the authentication device, end-user authentication is performed and the end-user is asked whether they give authorization to the client or not. The authorization server will receive the result of end-user authentication and authorization from the authentication device. After the authorization server receives the result from the authentication device, or even in the case where the server gave up receiving a response from the authentication device for some reasons, the server should call the `/backchannel/authentication/complete` API to tell Authlete the result. When the end-user was authenticated and authorization was granted to the client by the end-user, the authorization server should call the API with `result=AUTHORIZED`. In this successful case, the `subject` request parameter is mandatory. If the token delivery mode is `push`, the API will generate an access token, an ID token and optionally a refresh token. On the other hand, if the token delivery mode is `poll` or `ping`, the API will just update the database record so that `/auth/token` API can generate tokens later. When the authorization server received the decision of the end-user from the authentication device and it indicates that the end-user has rejected to give authorization to the client, the authorization server should call the API with `result=ACCESS\_DENIED`. In this case, if the token delivery mode is `push`, the API will generate an error response that contains the error response parameter and optionally the `error\_description` and error\_uri response parameters (if the `errorDescription` and `errorUri` request parameters have been given). On the other hand, if the token delivery mode is `poll` or `ping`, the API will just update the database record so that `/auth/token` API can generate an error response later. In any token delivery mode, the value of the error parameter will become `access\_denied`. When the authorization server could not get the result of end-user authentication and authorization from the authentication device for some reasons, the authorization server should call the API with `result=TRANSACTION\_FAILED`. In this error case, the API will behave in the same way as in the case of `ACCESS\_DENIED`. The only difference is that `expired\_token` is used as the value of the `error` parameter. The response from `/backchannel/authentication/complete` API has various parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the service implementation must take the steps described below. **SERVER\_ERROR** When the value of `action` is `SERVER\_ERROR`, it means either (1) that the request from the authorization server to Authlete was wrong, or (2) that an error occurred on Authlete side. When the backchannel token delivery mode is `ping` or `push`, `SERVER\_ERROR` is used only when an error is detected before the record of the ticket (which is included in the API call to `/backchannel/authentication/complete`) is retrieved from the database successfully. If an error is detected after the record of the ticket is retrieved from the database, `NOTIFICATION` is used instead of `SERVER\_ERROR`. When the backchannel token delivery mode is `poll`, `SERVER\_ERROR` is used regardless of whether it is before or after the record of the ticket is retrieved from the database. **NO\_ACTION** When the value of `action` is `NO\_ACTION`, it means that the authorization server does not have to take any immediate action. `NO\_ACTION` is returned when the backchannel token delivery mode is `poll`. In this case, the client will receive the final result at the token endpoint. **NOTIFICATION** When the value of `action` is `NOTIFICATION`, it means that the authorization server must send a notification to the client notification endpoint. According to the CIBA Core specification, the notification is an HTTP POST request whose request body is JSON and whose `Authorization` header contains the client notification token, which was included in the backchannel authentication request as the value of the `client\_notification\_token` request parameter, as a bearer token. When the backchannel token delivery mode is `ping`, the request body of the notification is JSON which contains the `auth\_req\_id` property only. When the backchannel token delivery mode is `push`, the request body will additionally contain an access token, an ID token and other properties. Note that when the backchannel token delivery mode is `poll`, a notification does not have to be sent to the client notification endpoint. In error cases, in the ping mode, however, the content of a notification is not different from the content in successful cases. That is, the notification contains the `auth\_req\_id` property only. The client will know the error when it accesses the token endpoint. On the other hand, in the `push` mode, in error cases, the content of a notification will include the `error` property instead of an access token and an ID token. The client will know the error by detecting that error is included in the notification. In any case, the value of `responseContent` is JSON which can be used as the request body of the notification. The client notification endpoint that the notification should be sent to the value of the `clientNotificationEndpoint` parameter. Likewise, the client notification token that the notification should include as a bearer token is the `clientNotificationToken` parameter. With these methods, the notification can be built like the following. ``` POST {clientNotificationEndpoint} HTTP/1.1 HOST: {The host of clientNotificationEndpoint} Authorization: Bearer {notificationToken} Content-Type: application/json {responseContent} ``` ## Path parameters - `serviceId` string, required ## Request body - BackchannelAuthenticationCompleteRequest - `ticket` string, required — The ticket issued by Authlete's `/backchannel/authentication` API. - `result` 'TRANSACTION_FAILED' | 'ACCESS_DENIED' | 'AUTHORIZED', required — The result of the end-user authentication and authorization. One of the following. Details are described in the description. - `subject` string, required — The subject (= unique identifier) of the end-user. - `sub` string — The value of the sub claim that should be used in the ID token. - `authTime` integer — The time at which the end-user was authenticated. Its value is the number of seconds from `1970-01-01`. - `acr` string — The reference of the authentication context class which the end-user authentication satisfied. - `claims` string — Additional claims which will be embedded in the ID token. - `properties` Property[] — The extra properties associated with the access token. - `key` string — The key part. - `value` string — The value part. - `hidden` boolean — The flag to indicate whether this property hidden from or visible to client applications. If `true`, this property is hidden from client applications. Otherwise, this property is visible to client applications. - `scopes` string[] — Scopes to replace the scopes specified in the original backchannel authentication request with. When nothing is specified for this parameter, replacement is not performed. - `idtHeaderParams` string — JSON that represents additional JWS header parameters for ID tokens. - `errorDescription` string — The description of the error. If this optional request parameter is given, its value is used as the value of the `error_description` property, but it is used only when the result is not `AUTHORIZED`. To comply with the specification strictly, the description must not include characters outside the set `%x20-21 / %x23-5B / %x5D-7E`. - `errorUri` string — The URI of a document which describes the error in detail. This corresponds to the `error_uri` property in the response to the client. - `consentedClaims` string[] — the claims that the user has consented for the client application to know. - `jwtAtClaims` string — Additional claims that are added to the payload part of the JWT access token. - `accessToken` string — The representation of an access token that may be issued as a result of the Authlete API call. - `accessTokenDuration` integer — The duration (in seconds) of the access token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored. - `refreshTokenDuration` integer — The duration (in seconds) of the refresh token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the refresh token in. In other cases, this request parameter is ignored. - `idTokenAudType` string — The type of the `aud` claim of the ID token being issued. Valid values are as follows. | Value | Description | | ----- | ----------- | | "array" | The type of the aud claim is always an array of strings. | | "string" | The type of the aud claim is always a single string. | | null | The type of the aud claim remains the same as before. | This request parameter takes precedence over the `idTokenAudType` property of the service. ## Response `200` Backchannel authentication completed successfully - BackchannelAuthenticationCompleteResponse - `resultCode` string — The code which represents the result of the API call. - `resultMessage` string — A short message which explains the result of the API call. - `action` 'SERVER_ERROR' | 'NO_ACTION' | 'NOTIFICATION' — The next action that the authorization server implementation should take. - `responseContent` string — The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. - `clientId` integer — The client ID of the client application that has made the backchannel authentication request. - `clientIdAlias` string — The client ID alias of the client application that has made the backchannel authentication request. - `clientIdAliasUsed` boolean — `true` if the value of the client_id request parameter included in the backchannel authentication request is the client ID alias. `false` if the value is the original numeric client ID. - `clientName` string — The name of the client application which has made the backchannel authentication request. - `deliveryMode` 'PING' | 'POLL' | 'PUSH' - `clientNotificationEndpoint` string — The client notification endpoint to which a notification needs to be sent. This corresponds to the `client_notification_endpoint` metadata of the client application. - `clientNotificationToken` string — The client notification token which needs to be embedded as a Bearer token in the Authorization header in the notification. This is the value of the `client_notification_token` request parameter included in the backchannel authentication request. - `authReqId` string — The newly issued authentication request ID. - `accessToken` string — The issued access token. - `refreshToken` string — The issued refresh token. - `idToken` string — The issued ID token. - `accessTokenDuration` integer — The duration of the access token in seconds. - `refreshTokenDuration` integer — The duration of the refresh token in seconds. - `idTokenDuration` integer — The duration of the ID token in seconds. - `jwtAccessToken` string — The issued access token in JWT format. - `resources` string[] — The resources specified by the `resource` request parameters or by the `resource` property in the request object. If both are given, the values in the request object should be set. See "Resource Indicators for OAuth 2.0" for details. - `authorizationDetails` AuthzDetails — The authorization details. This represents the value of the `authorization_details` request parameter in the preceding device authorization request which is defined in "OAuth 2.0 Rich Authorization Requests". - `elements` AuthorizationDetailsElement[] — Elements of this authorization details. - `type` string, required — The type of this element. From _"OAuth 2.0 Rich Authorization Requests"_: _"The type of authorization data as a string. This field MAY define which other elements are allowed in the request. This element is REQUIRED."_ This property is always NOT `null`. - `locations` string[] — The resources and/or resource servers. This property may be `null`. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the location of the resource or resource server. This is typically composed of URIs."_ This property may be `null`. - `actions` string[] — The actions. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of actions to be taken at the resource. The values of the strings are determined by the API being protected."_ This property may be `null`. - `dataTypes` string[] — From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of data being requested from the resource."_ This property may be `null`. - `identifier` string — The identifier of a specific resource. From _"OAuth 2.0 Rich Authorization Requests"_: _"A string identifier indicating a specific resource available at the API."_ This property may be `null`. - `privileges` string[] — The types or levels of privilege. From "OAuth 2.0 Rich Authorization Requests": _"An array of strings representing the types or levels of privilege being requested at the resource."_ This property may be `null`. - `otherFields` string — The RAR request in the JSON format excluding the pre-defined attributes such as `type` and `locations`. The content and semantics are specific to the deployment and the use case implemented. - `serviceAttributes` Pair[] — The attributes of this service that the client application belongs to. - `key` string — The key part. - `value` string — The value part. - `clientAttributes` Pair[] — The attributes of the client. - `key` string — The key part. - `value` string — The value part. - `grantId` string — the value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. - `clientEntityId` string — The entity ID of the client. - `clientEntityIdUsed` boolean — Flag which indicates whether the entity ID of the client was used when the request for the access token was made. - `metadataDocumentLocation` string, uri — The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. - `metadataDocumentUsed` boolean — Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. ## Other responses - `400` - `401` - `403` - `500` ## Changes - **2025-12-18** `504771740022` — 2 info - added the optional property `metadataDocumentLocation` to the response with the `200` status - added the optional property `metadataDocumentUsed` to the response with the `200` status [Change history](https://skmtc.dev/authlete/apis/authlete-api/changes/api/:serviceId/backchannel/authentication/complete/post.md) --- [API](https://skmtc.dev/authlete/apis/authlete-api.md) · [All operations](https://skmtc.dev/authlete/apis/authlete-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/authlete/authlete-api/revisions/8a534bc68775/schema)