Response from Authlete's /api/backchannel/authentication API.
More...
Properties | |
| BackchannelAuthenticationAction | Action [get, set] |
| The next action that the authorization server implementation should take. More... | |
| string | ResponseContent [get, set] |
| The response content which can be used to generate a response to the client application. More... | |
| long | ClientId [get, set] |
| The client ID of the client application. More... | |
| string | ClientIdAlias [get, set] |
| The client ID alias of the client application. More... | |
| bool | IsClientIdAliasUsed [get, set] |
| The flag which indicates whether the client ID alias was used in the backchannel authentication request. More... | |
| string | ClientName [get, set] |
| The name of the client application. More... | |
| DeliveryMode | DeliveryMode [get, set] |
| The backchannel token delivery mode of the client application. More... | |
| Scope[] | Scopes [get, set] |
| The scopes requested by the backchannel authentication request. More... | |
| string[] | ClaimNames [get, set] |
| The names of the claims which were requested indirectly via some special scopes. See 5.4. Requesting Claims using Scope Values in OpenID Connect Core 1.0 for details. More... | |
| string | ClientNotificationToken [get, set] |
The client notification token included in the backchannel authentication request. It is the value of the client_notification_token request parameter. More... | |
| string[] | Acrs [get, set] |
| The list of ACRs (Authentication Context Class References) requested by the backchannel authentication request. More... | |
| UserIdentificationHintType | HintType [get, set] |
| The type of the hint for end-user identification which was included in the backchannel authentication request. More... | |
| string | Hint [get, set] |
| The value of the hint for end-user identification. More... | |
| string | Sub [get, set] |
The value of the sub claim contained in the ID token hint included in the backchannel authentication request. More... | |
| string | BindingMessage [get, set] |
The binding message included in the backchannel authentication request. It is the value of the binding_message request parameter. More... | |
| string | UserCode [get, set] |
The user code included in the backchannel authentication request. It is the value of the user_code request parameter. More... | |
| bool | IsUserCodeRequired [get, set] |
| The flag which indicates whether a user code is required. More... | |
| int | RequestedExpiry [get, set] |
The requested expiry for the authentication request ID (auth_req_id). It is the value of the requested_expiry request parameter. More... | |
| string | RequestContext [get, set] |
The request context of the backchannel authentication request. It is the value of the request_context claim in the signed authentication request object and its format is JSON. request_context is a new claim added by the FAPI-CIBA profile. More... | |
| string[] | Resources [get, set] |
The resources specified by the resource request parameters or by the More... | |
| string[] | Warnings [get, set] |
| The warnings raised during processing the backchannel authentication request. More... | |
| string | Ticket [get, set] |
The ticket that is necessary for the implementation of the backchannel authentication endpoint to call /api/backchannel/authentication/* API. More... | |
 Properties inherited from ApiResponse | |
| string | ResultCode [get, set] |
The code of the result of an Authlete API call. For example, "A004001". More... | |
| string | ResultMessage [get, set] |
| The message of the result of an Authlete API call. For example, "[A001202] /client/get/list,
Authorization header is missing." More... | |
Response from Authlete's /api/backchannel/authentication API.
Authlete's /api/backchannel/authentication API returns JSON which can be mapped to this class. The authorization server implementation should retrieve the value of the action response parameter (which can be obtained via the Action property) from the response and take the following steps according to the value.
When the value of the Action property is BackchannelAuthenticationAction.BAD_REQUEST, it means that the backchannel authentication request from the client application was wrong.
The authorization server implementation should generate a response to the client application with 400 Bad Request and application/json.
In this case, ResponseContent returns a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the authorization server implementation should generate and return to the client application.
When the value of the Action property is BackchannelAuthenticationAction.UNAUTHORIZED, it means that client authentication of the backchannel authentication request failed. Note that client authentication is always required at the backchannel authentication endpoint. This implies that public clients are not allowed to use the backchannel authentication endpoint.
The authorization server implementation should generate a response to the client application with 401 Unauthorized and application/json.
In this case, ResponseContent returns a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the authorization server implementation should generate and return to the client application.
When the value of the Action property is BackchannelAuthenticationAction.INTERNAL_SERVER_ERROR, it means that the API call from the authorization server implementation was wrong or that an error occurred in Authlete.
In either case, from a viewpoint of the client application, it is an error on the server side. Therefore, the authorization server implementation should generate a response to the client application with 500 Internal Server Error and application/json.
In this case, ResponseContent returns a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the authorization server implementation should generate and return to the client application.
When the value of the Action property is BackchannelAuthenticationAction.USER_IDENTIFICATION, it means that the backchannel authentication request from the client application is valid. The authorization server implementation has to follow the steps below.
[END-USER IDENTIFICATION
The first step is to determine the subject (= unique identifier) of the end-user from whom the client application wants to get authorization.
According to the CIBA specification, a backchannel authentication request contains one (and only one) of the login_hint_token, id_token_hint and login_hint request parameters as a hint by which the authorization server identifies the subject of an end-user.
The authorization server implementation can know which hint is included in the backchannel authenticaiton request by checking the value of HintType property. The property holds a UserIdentificationHintType value that indicates which hint is included. For example, when the property holds UserIdentificationHintType.LOGIN_HINT, it means that the backchannel authentication request contains the login_hint request parameter as a hint.
The Hint property holds the value of the hint. For example, when the HintType property holds UserIdentificationHintType.LOGIN_HINT, Hint holds the value of the login_hint request parameter.
It is up to the authorization server implementation how to determine the subject of the end-user from the hint. There are few things Authlete can help. Only one thing Authlete can do is to set the value of the sub claim in the id_token_hint request parameter to the Sub property when the request parameter is used.
[END-USER IDENTIFICATION ERROR]
There are some cases where the authorization server implementation encounters an error during the user identification process. In any error case, the authorization server implementation has to return an HTTP response with the error response parameter to the client application. The following is an example of such error responses.
Authlete provides /api/backchannel/authenticaiton/fail API that builds the response body (JSON) of an error response. However, because it is easy to build an error response manually, you may choose not to call the API. One good thing in using the API is that the API call can trigger deletion of the ticket which has been issued from Authlete's /api/backchannel/authentication API. If you don't call /api/backchannel/authenticaiton/fail API, the ticket will continue to exist in the database until it is cleaned up by the batch program after the ticket expires.
Possible error cases that the authorization server implementation itself has to handle are as follows. Other error cases have already been covered by /api/backchannel/authentication API.
expired_login_hint_token:
The authorization server implementation detected that the hint presented by the login_hint_token request parameter has expired. Note that the format of login_hint_token is not described in the CIBA Core spec at all and so there is no consensus on how to detect expiration of login_hint_token. Interpretation of login_hint_token is left to each authorization server implementation.
unknown_user_id:
The authorization server implementation could not determine the subject of the end-user by the presented hint.
unauthorized_client:
The authorization server implementation has custom rules to reject backchannel authentication requests from some particular clients and found that the client which has made the backchannel authentication request is one of the particular clients. Note that /api/backchannel/authentication API does not return action=USER_IDENTIFICATION in cases where the client does not exist or client authentication has failed. Therefore, the authorization server implementation will never have to user the error code unauthorized_client unless the server has intentionally implemented custom rules to reject backchannel authentication requests based on clients.
missing_user_code:
The authorization server implementation has custom rules to require that a backchannel authentication request include a user code for some particular users and found that the user identified by the hint is one of the particular users. Note that /api/backchannel/authentication API does not return action=USER_IDENTIFICATION when both the backchannel_user_code_parameter_supported metadata of the server and the backchannel_user_code_parameter metadata of the client are true and the backchannel authentication request does not include the user_code request parameter. In this case, /api/backchannel/authentication API returns action=BAD_REQUEST with JSON containing "error":"missing_user_code". Therefore, the authorization server implementation will never have to use the error code missing_user_code unless the server has intentionally implemented custom rules to require a user code based on users even in the case where the backchannel_user_code_parameter metadata of the client which has made the backchannel authentication request is false.
invalid_user_code:
The authorization server implementation detected that the presented user code is invalid. Note that the format of user_code is not described in the CIBA Core spec at all and so there is no consensus on how to judge whether a user code is valid or not. It is up to each authorization server implementation how to handle user codes.
invalid_binding_message:
The authorization server implementation detected that the presented binding message is invalid. Note that the format of binding_message is not described in the CIBA Core spec at all and so there is no consensus on how to judge whether a binding message is valid or not. It is up to each authorization server implementation how to handle binding messages.
access_denied:
The authorization server implementation has custom rules to reject backchannel authentication requests without asking the end-user and respond to the client as if the end-user had rejected the request in some particular cases and found that the backchannel authentication requests is one of the particular cases. The authorization server implementation will never have to use the error code access_denied at this timing unless the server has intentionally implemented custom rules to reject backchannel authentication requests without asking th end-user and respond to the client as if the end-user had rejected the request.
[AUTH_REQ_ID ISSUE]
If the authorization server implementation has successfully determined the subject of the end-user, the next action is to return an HTTP response to the client application which contains auth_req_id.
Authlete provides /api/backchannel/authentication/issue API which generates a JSON containing auth_req_id, so, your next action is (1) call the API, (2) receive the response from the API, (3) build a response to the client application using the content of the API response, and (4) return the response to the client application. See the description of /api/backchannel/authentication/issue API for details.
[END-USER AUTHENTICATION AND AUTHORIZATION]
After sending a JSON containing auth_req_id back to the client application, the authorization server implementation starts to communicate with an authentication device of the end-user. It is assumed that end-user authentication is performed on the authentication device and the end-user confirms the content of the backchannel authentication request and grants authorization to the client application if everything is okay. The authorization server implementation must be able to receive the result of the end-user authentication and authorization from the authentication device.
How to communicate with an authentication device and achieve end-user authentication and authorization is up to each authorization server implementation, but the following request parameters of the backchannel authentication request should be taken into consideration in any implementation.
acr_values (Acrs property):
A backchannel authentication request may contain an array of ACRs (Authentication Context Class References) in preference order. If multiple authentication devices are registered for the end-user, the authorization server implementation should take the ACRs into consideration when selecting the best authentication device.
scope (Scopes property):
A backchannel authentication request always contains a list of scopes. At least, openid is included in the list (otherwise /api/backchannel/authentication API returns action=BAD_REQUESET). It would be better to show the requested scopes to the end-user on the authentication device or somewhere appropriate. If the scope request parameter contains address, email, phone and/or profile, they are interpreted as defined in 5.4. Requesting Claims using Scope Values of OpenID Connect Core 1.0. That is, they are expanded into a list of claim names. The ClaimNames property holds the expanded result.
bind_message (BindingMessage property):
A backchannel authentication request may contain a binding message. It is a human readable identifier or message intended to be displayed on both the consumption device (client application) and the authentication device.
user_code (UserCode property):
A backchannel authentication request may contain a user code. It is a secret code, such as password or pin, known only to the end-user but verifiable by the authorization server. The user code should be used to authorize sending a request to the authentication device.
[END-USER AUTHENTICATION AND AUTHORIZATION COMPLETION]
After receiving the result of end-user authentication and authorization, the authorization server implementation must call Authlete's /api/backchannel/authentication/complete API to tell Authlete the result and pass necessary data so that Authlete can generate an ID token, an access token and optionally a refresh token. See the description of the API for details.
[CLIENT NOTIFICATION]
When the backchannel token delivery mode is either "ping" or "push", the authorization server implementation must send a notification to the pre-registered notification endpoint of the client after the end-user authentication and authorization. In this case, the Action property of BackchannelAuthenticationCompleteResponse (a response from /api/backchannel/authentication/complete API) holds BackchannelAuthenticationCompleteAction.NOTIFICATION. See the description of /api/backchannel/authentication/complete API for details.
[TOKEN REQUEST]
When the backchannel token delivery mode is either "ping" or "poll", the client application will make one or more token requests to the token endpoint to get an ID token, an access token and optionally a refresh token.
A token request that corresponds to a backchannel authentication request uses urn:openid:params:grant-type:ciba as the value of the grant_type request parameter. Authlete's /api/auth/token API recognizes the grant type automatically and behaves properly, so the existing token endpoint implementation does not have to be changed to support CIBA.
Since version 1.3.0.
|
getset |
The list of ACRs (Authentication Context Class References) requested by the backchannel authentication request.
Basically, this property holds the value of the acr_values request parameter in the backchannel authentication request. However, because unsupported ACR values are dropped on Authlete side, if the acr_values request parameter contains unrecognized ACR values, the list this property holds becomes different from the value of the acr_values request parameter.
|
getset |
The next action that the authorization server implementation should take.
|
getset |
The binding message included in the backchannel authentication request. It is the value of the binding_message request parameter.
|
getset |
The names of the claims which were requested indirectly via some special scopes. See 5.4. Requesting Claims using Scope Values in OpenID Connect Core 1.0 for details.
|
getset |
The client ID of the client application.
|
getset |
The client ID alias of the client application.
|
getset |
The name of the client application.
|
getset |
The client notification token included in the backchannel authentication request. It is the value of the client_notification_token request parameter.
When the backchannel token delivery mode is "ping" or "push", the backchannel authentication request must include a client notification token.
|
getset |
The backchannel token delivery mode of the client application.
|
getset |
The value of the hint for end-user identification.
When the HintType property holds UserIdentificationHintType.ID_TOKEN_HINT, this property holds the value of the id_token_hint request parameter. Likewise, this property holds the value of the login_hint request parameter when the HintType property holds UserIdentificationHintType.LOGIN_HINT, or holds the value of the login_hint_token request parameter when the HintType property holds UserIdentificationHintType.LOGIN_HINT_TOKEN.
|
getset |
The type of the hint for end-user identification which was included in the backchannel authentication request.
When the backchannel authentication request contains id_token_hint, this property holds UserIdentificationHintType.ID_TOKEN_HINT. Likewise, this property holds UserIdentificationHintType.LOGIN_HINT when the request contains login_hint, or holds UserIdentificationHintType.LOGIN_HINT_TOKEN when the request contains login_hint_token.
|
getset |
The flag which indicates whether the client ID alias was used in the backchannel authentication request.
|
getset |
The flag which indicates whether a user code is required.
This property holds true when both the backchannel_user_code_parameter metadata of the client (= IsBcUserCodeRequired property of the Client class) and the backchannel_user_code_parameter_supported metadata of the server (= IsBackchannelUserCodeParameterSupported property of the Service class) are true.
|
getset |
The request context of the backchannel authentication request. It is the value of the request_context claim in the signed authentication request object and its format is JSON. request_context is a new claim added by the FAPI-CIBA profile.
This property is null if the backchannel authentication request does not include a request request parameter or the JWT specified by the request parameter does not include a request_context claim.
Since version 1.4.0.
|
getset |
The requested expiry for the authentication request ID (auth_req_id). It is the value of the requested_expiry request parameter.
|
getset |
The resources specified by the resource request parameters or by the
resource property in the request object in the preceding backchannel authentication request. If both are given, the values in the request object take precedence. See RFC 8707 (Resource Indicators for OAuth 2.0) for details.
Since version 1.4.0.
|
getset |
The response content which can be used to generate a response to the client application.
When this property holds a non-null value, it is JSON containing error information. When the Action property holds USER_IDENTIFICATION, the value of this property is null.
|
getset |
The scopes requested by the backchannel authentication request.
Basically, this property holds the value of the scope request parameter in the backchannel authentication request. However, because unregistered scopes are dropped on Authlete side, if the scope request parameter contains unknown scopes, the list held by this property becomes different from the value of the scope request parameter.
Note that Description property and Descriptions property of each element (Scope instance) in the array held by this property always null even if descriptions of the scopes are registered.
|
getset |
The value of the sub claim contained in the ID token hint included in the backchannel authentication request.
This property works only when the backchannel authentication request contains the id_token_hint request parameter.
|
getset |
The ticket that is necessary for the implementation of the backchannel authentication endpoint to call /api/backchannel/authentication/* API.
|
getset |
The user code included in the backchannel authentication request. It is the value of the user_code request parameter.
|
getset |
The warnings raised during processing the backchannel authentication request.
1.8.18