Complete Backchannel Authentication

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}