com.authlete.common.dto.BackchannelAuthenticationResponse Maven / Gradle / Ivy
Show all versions of authlete-java-common Show documentation
/*
* Copyright (C) 2018-2023 Authlete, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.authlete.common.dto;
import java.net.URI;
import com.authlete.common.types.ClientAuthMethod;
import com.authlete.common.types.DeliveryMode;
import com.authlete.common.types.GMAction;
import com.authlete.common.types.UserIdentificationHintType;
/**
* Response from Authlete's {@code /api/backchannel/authentication} API.
*
*
* Authlete's {@code /api/backchannel/authentication} API returns JSON which
* can be mapped to this class. The authorization server implementation should
* retrieve the value of {@code action} from the response and take the
* following steps according to the value.
*
*
*
* - {@link Action#BAD_REQUEST BAD_REQUEST}
* -
*
* When the value of {@code action} is {@code 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 {@code 400 Bad Request} and {@code application/json}.
*
*
*
* The {@link #getResponseContent()} method 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.
*
*
*
* HTTP/1.1 400 Bad Request
* Content-Type: application/json
* Cache-Control: no-store
* Pragma: no-cache
*
* (The value returned from {@link #getResponseContent()})
*
*
*
* - {@link Action#UNAUTHORIZED UNAUTHORIZED}
* -
*
* When the value of {@code action} is {@code 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 {@code 401 Unauthorized} and {@code application/json}.
*
*
*
* The {@link #getResponseContent()} method 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.
*
*
*
* HTTP/1.1 401 Unauthorized
* WWW-Authenticate: (challenge)
* Content-Type: application/json
* Cache-Control: no-store
* Pragma: no-cache
*
* (The value returned from {@link #getResponseContent()})
*
*
*
* - {@link Action#INTERNAL_SERVER_ERROR INTERNAL_SERVER_ERROR}
* -
*
* When the value of {@code action} is {@code 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
* {@code 500 Internal Server Error} and {@code application/json}.
*
*
*
* The {@link #getResponseContent()} method 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.
*
*
*
* HTTP/1.1 500 Internal Server Error
* Content-Type: application/json
* Cache-Control: no-store
* Pragma: no-cache
*
* (The value returned from {@link #getResponseContent()})
*
*
*
* - {@link Action#USER_IDENTIFICATION USER_IDENTIFICATION}
* -
*
* When the value of {@code action} is {@code 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 {@code login_hint_token},
* {@code id_token_hint} and {@code 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 authentication request by calling the {@link #getHintType()}
* method. The method returns a {@link UserIdentificationHintType} instance
* that indicates which hint is included. For example, when the method returns
* {@link UserIdentificationHintType#LOGIN_HINT LOGIN_HINT}, it means that the
* backchannel authentication request contains the {@code login_hint} request
* parameter as a hint.
*
*
*
*
* The {@link #getHint()} method returns the value of the hint. For example,
* when the {@code getHintType()} method returns {@code LOGIN_HINT}, the
* {@code getHint()} method returns the value of the {@code 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 let the {@link #getSub()} method
* return the value of the {@code sub} claim in the {@code id_token_hint}
* request parameter 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 {@code error} response parameter to the client application. The
* following is an example of such error responses.
*
*
*
*
* HTTP/1.1 400 Bad Request
* Content-Type: application/json
* Cache-Control: no-store
* Pragma: no-cache
*
* {"error":"unknown_user_id"}
*
*
*
* Authlete provides {@code /api/backchannel/authentication/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
* {@code /api/backchannel/authentication} API. If you don't call
* {@code /api/backchannel/authentication/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 {@code /api/backchannel/authentication} API.
*
*
*
*
*
*
* {@code error}
* description
*
*
*
*
* {@code expired_login_hint_token}
*
*
* The authorization server implementation detected that the hint
* presented by the {@code login_hint_token} request parameter has
* expired.
*
*
*
* Note that the format of {@code 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 {@code login_hint_token}. Interpretation of
* {@code login_hint_token} is left to each authorization server
* implementation.
*
*
*
*
* {@code unknown_user_id}
*
*
* The authorization server implementation could not determine the
* subject of the end-user by the presented hint.
*
*
*
*
* {@code 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 {@code /api/backchannel/authentication} API does not
* return {@code 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 use the error
* code {@code unauthorized_client} unless the server has intentionally
* implemented custom rules to reject backchannel authentication
* requests based on clients.
*
*
*
*
* {@code 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 {@code /api/backchannel/authentication} API does not
* return {@code action=USER_IDENTIFICATION} when both the
* {@code backchannel_user_code_parameter_supported} metadata of the
* server and the {@code backchannel_user_code_parameter} metadata of
* the client are {@code true} and the backchannel authentication
* request does not include the {@code user_code} request parameter.
* In this case, {@code /api/backchannel/authentication} API returns
* {@code action=BAD_REQUEST} with JSON containing
* {@code "error":"missing_user_code"}. Therefore, the authorization
* server implementation will never have to use the error code
* {@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 {@code backchannel_user_code_parameter}
* metadata of the client which has made the backchannel authentication
* request is {@code false}.
*
*
*
*
* {@code invalid_user_code}
*
*
* The authorization server implementation detected that the presented
* user code is invalid.
*
*
*
* Note that the format of {@code 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.
*
*
*
*
* {@code invalid_binding_message}
*
*
* The authorization server implementation detected that the presented
* binding message is invalid.
*
*
*
* Note that the format of {@code 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.
*
*
*
*
* {@code invalid_target}
*
*
* The authorization server implementation rejects the requested target
* resources.
*
*
*
* The error code {@code "invalid_target"} is from "Resource Indicators
* for OAuth 2.0". The specification defines the {@code "resource"}
* request parameter. By using the parameter, client applications can
* request target resources that should be bound to the access token being
* issued. If the authorization server wants to reject the request, call
* {@code /api/backchannel/authentication/fail} API with
* {@code INVALID_TARGET}.
*
*
*
* Note that "Resource Indicators for OAuth 2.0" is supported since
* Authlete 2.2. Older versions don't recognize the {@code resource} request
* parameter, so {@link #getResources()} always returns null if the Authlete
* server you are using is older than 2.2.
*
*
*
*
* {@code access_denined}
*
*
* 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
* request is one of the particular cases.
*
*
*
* The authorization server implementation will never have to use the
* error code {@code access_denied} at this timing unless the server
* has intentionally implemented 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.
*
*
*
*
*
*
*
*
* -
*
[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 {@code auth_req_id}.
*
*
*
*
* Authlete provides {@code /api/backchannel/authentication/issue} API which
* generates a JSON containing {@code 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 {@code /api/backchannel/authentication/issue} API for details.
*
*
*
*
* -
*
[END-USER AUTHENTICATION AND AUTHORIZATION]
*
*
*
* After sending a JSON containing {@code 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.
*
*
*
*
*
*
* parameter
* method
* description
*
*
*
*
* {@code acr_values}
* {@link #getAcrs()}
*
*
* 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.
*
*
*
* {@code scope}
* {@link #getScopes()}, {@link #getDynamicScopes()}
*
*
* A backchannel authentication request always contains a list of
* scopes. At least, {@code openid} is included in the list (otherwise
* {@code /api/backchannel/authentication} API returns
* {@code action=BAD_REQUEST}). It would be better to show the
* requested scopes to the end-user on the authentication device or
* somewhere appropriate.
*
*
*
* If the {@code scope} request parameter contains {@code address},
* {@code email}, {@code phone} and/or {@code 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 {@link #getClaimNames()} method returns the expanded result.
*
*
* The {@code scope} request parameter may contain dynamic scopes.
* They are obtained through {@link #getDynamicScopes()} method.
* See the description of the {@link DynamicScope} class for details
* about dynamic scopes.
*
*
*
*
* {@code binding_message}
* {@link #getBindingMessage()}
*
*
* 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.
*
*
*
*
* {@code user_code}
* {@link #getUserCode()}
*
*
* 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
* {@code /api/backchannel/authentication/complete} 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
* {@link DeliveryMode#PING ping} or {@link DeliveryMode#PUSH 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,
* {@link BackchannelAuthenticationCompleteResponse#getAction() getAction()}
* method of {@link BackchannelAuthenticationCompleteResponse} (a response
* from {@code /api/backchannel/authentication/complete} API) returns
* {@link BackchannelAuthenticationCompleteResponse.Action#NOTIFICATION
* NOTIFICATION}. See the description of
* {@code /api/backchannel/authentication/complete} API for details.
*
*
*
*
* -
*
[TOKEN REQUEST]
*
*
*
* When the backchannel token delivery mode is either
* {@link DeliveryMode#PING ping} or {@link DeliveryMode#POLL poll}, the
* client application will make a token request 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 {@code urn:openid:params:grant-type:ciba} as
* the value of the {@code grant_type} request parameter. Authlete's
* {@code /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 2.32
*/
public class BackchannelAuthenticationResponse extends ApiResponse
{
private static final long serialVersionUID = 11L;
/**
* The next action that the OpenID provider implementation should take.
*/
public enum Action
{
/**
* The backchannel authentication request is invalid. The authorization
* server implementation should return an error response with
* {@code 400 Bad Request} and {@code application/json} to the client
* application.
*/
BAD_REQUEST,
/**
* Client authentication of the backchannel authentication request
* failed. The authorization server implementation should return an
* error response with {@code 401 Unauthorized} and
* {@code application/json} to the client application.
*/
UNAUTHORIZED,
/**
* The API call from the authorization server implementation was wrong
* or an error occurred on Authlete side. The authorization server
* implementation should return an error response with
* {@code 500 Internal Server Error} and {@code application/json} to
* the client application.
*/
INTERNAL_SERVER_ERROR,
/**
* The backchannel authentication request was valid. The authorization
* server implementation is required to (1) identify the subject of the
* end-user from the given hint, (2) issue {@code auth_req_id} to the
* client application, (3) communicate with an authentication device of
* the end-user to perform end-user authentication and authorization, etc.
* See the API document of {@link BackchannelAuthenticationResponse}
* for details.
*/
USER_IDENTIFICATION,
}
/**
* @since Authlete 2.0.0
*/
private Action action;
/**
* @since Authlete 2.0.0
*/
private String responseContent;
/**
* @since Authlete 2.0.0
*/
private long clientId;
/**
* @since Authlete 2.0.0
*/
private String clientIdAlias;
/**
* @since Authlete 2.0.0
*/
private boolean clientIdAliasUsed;
/**
* @since Authlete 2.3.0
*/
private URI clientEntityId;
/**
* @since Authlete 2.3.0
*/
private boolean clientEntityIdUsed;
/**
* @since Authlete 2.0.0
*/
private String clientName;
/**
* @since Authlete 2.3.13
*/
private ClientAuthMethod clientAuthMethod;
/**
* @since Authlete 2.0.0
*/
private DeliveryMode deliveryMode;
/**
* @since Authlete 2.0.0
*/
private Scope[] scopes;
/**
* @since Authlete 2.2.8
*/
private DynamicScope[] dynamicScopes;
/**
* @since Authlete 2.0.0
*/
private String[] claimNames;
/**
* @since Authlete 2.0.0
*/
private String clientNotificationToken;
/**
* @since Authlete 2.0.0
*/
private String[] acrs;
/**
* @since Authlete 2.0.0
*/
private UserIdentificationHintType hintType;
/**
* @since Authlete 2.0.0
*/
private String hint;
/**
* @since Authlete 2.0.0
*/
private String sub;
/**
* @since Authlete 2.0.0
*/
private String bindingMessage;
/**
* @since Authlete 2.0.0
*/
private String userCode;
/**
* @since Authlete 2.0.0
*/
private boolean userCodeRequired;
/**
* @since Authlete 2.0.0
*/
private int requestedExpiry;
/**
* @since Authlete 2.0.0
*/
private String requestContext;
/**
* @since Authlete 2.2.1
*/
private URI[] resources;
/**
* @since Authlete 2.2.0
*/
private AuthzDetails authorizationDetails;
/**
* @since Authlete 2.3.0
*/
private GMAction gmAction;
/**
* @since Authlete 2.3.0
*/
private String grantId;
/**
* @since Authlete 2.3.0
*/
private String grantSubject;
/**
* @since Authlete 2.3.0
*/
private Grant grant;
/**
* @since Authlete 2.2.3
*/
private Pair[] serviceAttributes;
/**
* @since Authlete 2.2.3
*/
private Pair[] clientAttributes;
/**
* @since Authlete 2.0.0
*/
private String[] warnings;
/**
* @since Authlete 2.0.0
*/
private String ticket;
/**
* Get the next action that the implementation of the backchannel
* authentication endpoint should take.
*
* @return
* The next action.
*/
public Action getAction()
{
return action;
}
/**
* Set the next action that the implementation of the backchannel
* authentication endpoint should take.
*
* @param action
* The next action.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setAction(Action action)
{
this.action = action;
return this;
}
/**
* Get the content that can be used to generate a response to the client
* application.
*
*
* When this method returns a non-null value, it is JSON containing error
* information. When {@link #getAction()} returns
* {@link Action#USER_IDENTIFICATION USER_IDENTIFICATION}, this method
* returns {@code null}.
*
*
* @return
* The content of a response to the client.
*/
public String getResponseContent()
{
return responseContent;
}
/**
* Set the content that can be used to generate a response to the client
* application.
*
* @param responseContent
* The content of a response to the client.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setResponseContent(String responseContent)
{
this.responseContent = responseContent;
return this;
}
/**
* Get the client ID of the client application that has made the
* backchannel authentication request.
*
* @return
* The client ID of the client application.
*/
public long getClientId()
{
return clientId;
}
/**
* Set the client ID of the client application that has made the
* backchannel authentication request.
*
* @param clientId
* The client ID of the client application.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setClientId(long clientId)
{
this.clientId = clientId;
return this;
}
/**
* Get the client ID alias of the client application that has made the
* backchannel authentication request.
*
* @return
* The client ID alias of the client application.
*/
public String getClientIdAlias()
{
return clientIdAlias;
}
/**
* Set the client ID alias of the client application that has made the
* backchannel authentication request.
*
* @param alias
* The client ID alias of the client application.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setClientIdAlias(String alias)
{
this.clientIdAlias = alias;
return this;
}
/**
* Get the flag which indicates whether the client ID alias was used in
* the backchannel authentication request.
*
* @return
* {@code true} if the client ID alias was used in the request.
*/
public boolean isClientIdAliasUsed()
{
return clientIdAliasUsed;
}
/**
* Set the flag which indicates whether the client ID alias was used in
* the backchannel authentication request.
*
* @param used
* {@code true} to indicate that the client ID alias was used in
* the request.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setClientIdAliasUsed(boolean used)
{
this.clientIdAliasUsed = used;
return this;
}
/**
* Get the entity ID of the client.
*
*
* "Entity ID" is a technical term defined in OpenID
* Federation 1.0.
*
*
* @return
* The entity ID of the client.
*
* @since 3.37
* @since Authlete 2.3
*
* @see OpenID Federation 1.0
*/
public URI getClientEntityId()
{
return clientEntityId;
}
/**
* Set the entity ID of the client.
*
*
* "Entity ID" is a technical term defined in OpenID
* Federation 1.0.
*
*
* @param entityId
* The entity ID of the client.
*
* @return
* {@code this} object.
*
* @since 3.37
* @since Authlete 2.3
*
* @see OpenID Federation 1.0
*/
public BackchannelAuthenticationResponse setClientEntityId(URI entityId)
{
this.clientEntityId = entityId;
return this;
}
/**
* Get the flag which indicates whether the entity ID of the client was
* used in the backchannel authentication request as a client ID.
*
*
* "Entity ID" is a technical term defined in OpenID
* Federation 1.0.
*
*
* @return
* {@code true} if the entity ID of the client was used in the
* request as a client ID.
*
* @since 3.37
* @since Authlete 2.3
*
* @see OpenID Federation 1.0
*/
public boolean isClientEntityIdUsed()
{
return clientEntityIdUsed;
}
/**
* Set the flag which indicates whether the entity ID of the client was
* used in the backchannel authentication request as a client ID.
*
*
* "Entity ID" is a technical term defined in OpenID
* Federation 1.0.
*
*
* @param used
* {@code true} to indicate that the entity ID of the client was
* used in the request as a client ID.
*
* @return
* {@code this} object.
*
* @since 3.37
* @since Authlete 2.3
*
* @see OpenID Federation 1.0
*/
public BackchannelAuthenticationResponse setClientEntityIdUsed(boolean used)
{
this.clientEntityIdUsed = used;
return this;
}
/**
* Get the client identifier used in the backchannel authentication
* request.
*
*
* When {@link #isClientIdAliasUsed()} returns {@code true}, this method
* returns the same value as {@link #getClientIdAlias()} does. Otherwise,
* if {@link #isClientEntityIdUsed()} returns {@code true}, this method
* returns the same value as {@link #getClientEntityId()}{@code .toString()}
* does. In other cases, this method returns the string representation of
* the value returned from {@link #getClientId()}.
*
*
* @return
* The client identifier used in the backchannel authentication
* request.
*/
public String getClientIdentifier()
{
if (clientIdAliasUsed)
{
return clientIdAlias;
}
else if (clientEntityIdUsed)
{
return clientEntityId.toString();
}
else
{
return String.valueOf(clientId);
}
}
/**
* Get the name of the client application which has made the backchannel
* authentication request.
*
* @return
* The name of the client application.
*/
public String getClientName()
{
return clientName;
}
/**
* Set the name of the client application which has made the backchannel
* authentication request.
*
* @param name
* The name of the client application.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setClientName(String name)
{
this.clientName = name;
return this;
}
/**
* Get the client authentication method that should be performed at the
* backchannel authentication endpoint.
*
*
* If the client could not be identified by the information in the request,
* this method returns {@code null}.
*
*
* @return
* The client authentication method that should be performed at
* the backchannel authentication endpoint.
*
* @since 2.50
*/
public ClientAuthMethod getClientAuthMethod()
{
return clientAuthMethod;
}
/**
* Set the client authentication method that should be performed at the
* backchannel authentication endpoint.
*
* @param method
* The client authentication method that should be performed at
* the backchannel authentication endpoint.
*
* @return
* {@code this} object.
*
* @since 2.50
*/
public BackchannelAuthenticationResponse setClientAuthMethod(ClientAuthMethod method)
{
this.clientAuthMethod = method;
return this;
}
/**
* Get the backchannel token delivery mode of the client application.
*
* @return
* The backchannel token delivery mode.
*/
public DeliveryMode getDeliveryMode()
{
return deliveryMode;
}
/**
* Set the backchannel token delivery mode of the client application.
*
* @param mode
* The backchannel token delivery mode.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setDeliveryMode(DeliveryMode mode)
{
this.deliveryMode = mode;
return this;
}
/**
* Get the scopes requested by the backchannel authentication request.
*
*
* Basically, this method returns the value of the {@code "scope"} request
* parameter in the backchannel authentication request. However, because
* unregistered scopes are dropped on Authlete side, if the {@code "scope"}
* request parameter contains unknown scopes, the list returned by this
* method becomes different from the value of the {@code "scope"} request
* parameter.
*
*
*
* Note that {@link Scope#getDescription()} method and
* {@link Scope#getDescriptions()} method of each element ({@link Scope}
* instance) in the array returned from this method always return
* {@code null} even if descriptions of the scopes are registered.
*
*
* @return
* The requested scopes.
*/
public Scope[] getScopes()
{
return scopes;
}
/**
* Set the scopes requested by the backchannel authentication request.
*
* @param scopes
* The requested scopes.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setScopes(Scope[] scopes)
{
this.scopes = scopes;
return this;
}
/**
* Get the dynamic scopes which the client application requested
* by the {@code scope} request parameter. See the description of
* {@link DynamicScope} for details.
*
* @return
* The list of dynamic scopes.
*
* @since 2.92
*
* @see DynamicScope
*/
public DynamicScope[] getDynamicScopes()
{
return dynamicScopes;
}
/**
* Set the dynamic scopes which the client application requested
* by the {@code scope} request parameter. See the description of
* {@link DynamicScope} for details.
*
* @param dynamicScopes
* The list of dynamic scopes.
*
* @return
* {@code this} object.
*
* @since 2.92
*
* @see DynamicScope
*/
public BackchannelAuthenticationResponse setDynamicScopes(DynamicScope[] dynamicScopes)
{
this.dynamicScopes = dynamicScopes;
return this;
}
/**
* Get 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.
*
* @return
* The names of the requested claims.
*/
public String[] getClaimNames()
{
return claimNames;
}
/**
* Set the names of the claims which were requested indirectly via some
* special scopes.
*
* @param names
* The names of the requested claims.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setClaimNames(String[] names)
{
this.claimNames = names;
return this;
}
/**
* Get the client notification token included in the backchannel
* authentication request. It is the value of the
* {@code client_notification_token} request parameter.
*
*
* When the backchannel token delivery mode is {@code "ping"} or
* {@code "push"}, the backchannel authentication request must include a
* client notification token.
*
*
* @return
* The client notification token included in the backchannel
* authentication request.
*/
public String getClientNotificationToken()
{
return clientNotificationToken;
}
/**
* Set the client notification token included in the backchannel
* authentication request. It is the value of the
* {@code client_notification_token} request parameter.
*
*
* When the backchannel token delivery mode is {@code "ping"} or
* {@code "push"}, the backchannel authentication request must include a
* client notification token.
*
*
* @param token
* The client notification token included in the backchannel
* authentication request.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setClientNotificationToken(String token)
{
this.clientNotificationToken = token;
return this;
}
/**
* Get the list of ACR values requested by the backchannel authentication
* request.
*
*
* Basically, this method returns the value of the {@code "acr_values"}
* request parameter in the backchannel authentication request. However,
* because unsupported ACR values are dropped on Authlete side, if the
* {@code "acr_values"} request parameter contains unrecognized ACR
* values, the list returned by this method becomes different from the
* value of the {@code "acr_values"} request parameter.
*
*
* @return
* The list of requested ACR values.
*/
public String[] getAcrs()
{
return acrs;
}
/**
* Set the list of ACR values requested by the backchannel authentication
* request.
*
* @param acrs
* The list of requested ACR values.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setAcrs(String[] acrs)
{
this.acrs = acrs;
return this;
}
/**
* Get the type of the hint for end-user identification which was
* included in the backchannel authentication request.
*
*
* When the backchannel authentication request contains
* {@code "id_token_hint"}, this method returns
* {@link UserIdentificationHintType#ID_TOKEN_HINT ID_TOKEN_HINT}.
* Likewise, this method returns
* {@link UserIdentificationHintType#LOGIN_HINT LOGIN_HINT} when the
* request contains {@code "login_hint"}, or returns
* {@link UserIdentificationHintType#LOGIN_HINT_TOKEN LOGIN_HINT_TOKEN}
* when the request contains {@code "login_hint_token"}.
*
*
*
* Note that a backchannel authentication request must include one and
* only one hint among {@code "id_token_hint"}, {@code "login_hint"} and
* {@code "login_hint_token"}.
*
*
* @return
* The type of the hint for end-user identification.
*/
public UserIdentificationHintType getHintType()
{
return hintType;
}
/**
* Set the type of the hint for end-user identification which was
* included in the backchannel authentication request.
*
* @param hintType
* The type of the hint for end-user identification.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setHintType(UserIdentificationHintType hintType)
{
this.hintType = hintType;
return this;
}
/**
* Get the value of the hint for end-user identification.
*
*
* When {@link #getHintType()} returns
* {@link UserIdentificationHintType#ID_TOKEN_HINT ID_TOKEN_HINT},
* this method returns the value of the {@code "id_token_hint"} request
* parameter. Likewise, this method returns the value of the
* {@code "login_hint"} request parameter when {@link #getHintType()}
* returns {@link UserIdentificationHintType#LOGIN_HINT LOGIN_HINT},
* or returns the value of the {@code "login_hint_token"} request
* parameter when {@link #getHintType()} returns
* {@link UserIdentificationHintType#LOGIN_HINT_TOKEN LOGIN_HINT_TOKEN}.
*
*
* @return
* The value of the hint for end-user identification.
*/
public String getHint()
{
return hint;
}
/**
* Set the value of the hint for end-user identification.
*
* @param hint
* The value of the hint for end-user identification.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setHint(String hint)
{
this.hint = hint;
return this;
}
/**
* Get the value of the {@code "sub"} claim contained in the ID token hint
* included in the backchannel authentication request.
*
*
* This method works only when the backchannel authentication request
* contains the {@code "id_token_hint"} request parameter.
*
*
* @return
* The value of the {@code "sub"} claim contained in the ID token
* hint.
*/
public String getSub()
{
return sub;
}
/**
* Set the value of the {@code "sub"} claim contained in the ID token hint
* included in the backchannel authentication request.
*
* @param sub
* The value of the {@code "sub"} claim contained in the ID token
* hint.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setSub(String sub)
{
this.sub = sub;
return this;
}
/**
* Get the user code included in the backchannel authentication request.
* It is the value of the {@code "user_code"} request parameter.
*
* @return
* The user code.
*/
public String getUserCode()
{
return userCode;
}
/**
* Set the user code included in the backchannel authentication request.
* It is the value of the {@code "user_code"} request parameter.
*
* @param userCode
* The user code.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setUserCode(String userCode)
{
this.userCode = userCode;
return this;
}
/**
* Get the requested expiry for the authentication request ID
* ({@code auth_req_id}). It is the value of the {@code "requested_expiry"}
* request parameter.
*
* @return
* The requested expiry in seconds.
*
* @since 2.35
*/
public int getRequestedExpiry()
{
return requestedExpiry;
}
/**
* Set the requested expiry for the authentication request ID
* ({@code auth_req_id}). It is the value of the {@code "requested_expiry"}
* request parameter.
*
* @param seconds
* The requested expiry in seconds.
*
* @return
* {@code this} object.
*
* @since 2.35
*/
public BackchannelAuthenticationResponse setRequestedExpiry(int seconds)
{
this.requestedExpiry = seconds;
return this;
}
/**
* Get the flag which indicates whether a user code is required.
*
*
* This method returns {@code true} when both the
* {@code backchannel_user_code_parameter} metadata of the client
* (= {@link com.authlete.common.dto.Client Client}'s
* {@code bcUserCodeRequired} property) and the
* {@code backchannel_user_code_parameter_supported} metadata of the
* service (= {@link com.authlete.common.dto.Service Service}'s
* {@code backchannelUserCodeParameterSupported} property) are
* {@code true}.
*
*
* @return
* {@code true} when a user code is required.
*
* @since 2.33
*/
public boolean isUserCodeRequired()
{
return userCodeRequired;
}
/**
* Set the flag which indicates whether a user code is required.
*
* @param required
* {@code true} to indicate that a user code is required.
*
* @return
* {@code this} object.
*
* @since 2.33
*/
public BackchannelAuthenticationResponse setUserCodeRequired(boolean required)
{
this.userCodeRequired = required;
return this;
}
/**
* Get the binding message included in the backchannel authentication
* request. It is the value of the {@code "binding_message"} request
* parameter.
*
* @return
* The binding message.
*/
public String getBindingMessage()
{
return bindingMessage;
}
/**
* Set the binding message included in the backchannel authentication
* request. It is the value of the {@code "binding_message"} request
* parameter.
*
* @param message
* The binding message.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setBindingMessage(String message)
{
this.bindingMessage = message;
return this;
}
/**
* Get the request context of the backchannel authentication request. It
* is the value of the {@code "request_context"} claim in the signed
* authentication request and its format is JSON. {@code "request_context"}
* is a new claim added by the FAPI-CIBA profile.
*
*
* This method returns {@code null} if the backchannel authentication
* request does not include a {@code "request"} request parameter or
* the JWT specified by the request parameter does not include a
* {@code "request_context"} claim.
*
*
* @return
* The request context in JSON format.
*
* @since 2.45
*/
public String getRequestContext()
{
return requestContext;
}
/**
* Set the request context of the backchannel authentication request. It
* is the value of the {@code "request_context"} claim in the signed
* authentication request and its format is JSON. {@code "request_context"}
* is a new claim added by the FAPI-CIBA profile.
*
* @param context
* The request context in JSON format.
*
* @return
* {@code this} object.
*
* @since 2.45
*/
public BackchannelAuthenticationResponse setRequestContext(String context)
{
this.requestContext = context;
return this;
}
/**
* Get the resources specified by the {@code resource} request parameters
* or by the {@code resource} property in the request object. If both are
* given, the values in the request object take precedence.
* See "Resource Indicators for OAuth 2.0" for details.
*
* @return
* Target resources.
*
* @since 2.62
*/
public URI[] getResources()
{
return resources;
}
/**
* Set the resources specified by the {@code resource} request parameters
* or by the {@code 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.
*
* @param resources
* Target resources.
*
* @return
* {@code this} object.
*
* @since 2.62
*/
public BackchannelAuthenticationResponse setResources(URI[] resources)
{
this.resources = resources;
return this;
}
/**
* Get the authorization details. This represents the value of the
* {@code "authorization_details"} request parameter which is defined in
* "OAuth 2.0 Rich Authorization Requests".
*
* @return
* Authorization details.
*
* @since 2.56
*/
public AuthzDetails getAuthorizationDetails()
{
return authorizationDetails;
}
/**
* Set the authorization details. This represents the value of the
* {@code "authorization_details"} request parameter which is defined in
* "OAuth 2.0 Rich Authorization Requests".
*
* @param details
* Authorization details.
*
* @return
* {@code this} object.
*
* @since 2.56
*/
public BackchannelAuthenticationResponse setAuthorizationDetails(AuthzDetails details)
{
this.authorizationDetails = details;
return this;
}
/**
* Get the value of the {@code grant_management_action} request parameter.
*
*
* The {@code grant_management_action} request parameter is defined in
* Grant
* Management for OAuth 2.0, which is supported by Authlete 2.3 and
* newer versions.
*
*
* @return
* A grant management action. {@code null} or one of
* {@link GMAction#CREATE CREATE}, {@link GMAction#REPLACE REPLACE}
* and {@link GMAction#MERGE MERGE}.
*
* @see Grant Management for OAuth 2.0
*
* @since 3.1
*/
public GMAction getGmAction()
{
return gmAction;
}
/**
* Set the value of the {@code grant_management_action} request parameter.
*
*
* The {@code grant_management_action} request parameter is defined in
* Grant
* Management for OAuth 2.0, which is supported by Authlete 2.3 and
* newer versions.
*
*
* @param action
* A grant management action. {@code null} or one of
* {@link GMAction#CREATE CREATE}, {@link GMAction#REPLACE REPLACE}
* and {@link GMAction#MERGE MERGE}.
*
* @return
* {@code this} object.
*
* @see Grant Management for OAuth 2.0
*
* @since 3.1
*/
public BackchannelAuthenticationResponse setGmAction(GMAction action)
{
this.gmAction = action;
return this;
}
/**
* Get the value of the {@code grant_id} request parameter.
*
*
* The {@code grant_id} request parameter is defined in
* Grant
* Management for OAuth 2.0, which is supported by Authlete 2.3 and
* newer versions.
*
*
* @return
* A grant ID.
*
* @see Grant Management for OAuth 2.0
*
* @since 3.1
*/
public String getGrantId()
{
return grantId;
}
/**
* Set the value of the {@code grant_id} request parameter.
*
*
* The {@code grant_id} request parameter is defined in
* Grant
* Management for OAuth 2.0, which is supported by Authlete 2.3 and
* newer versions.
*
*
* @param grantId
* A grant ID.
*
* @see Grant Management for OAuth 2.0
*
* @return
* {@code this} object.
*
* @since 3.1
*/
public BackchannelAuthenticationResponse setGrantId(String grantId)
{
this.grantId = grantId;
return this;
}
/**
* Get the subject of the user who has given the grant which is identified
* by the {@code grant_id} request parameter.
*
*
* Authlete 2.3 and newer versions support Grant Management
* for OAuth 2.0. A backchannel authentication request may contain a
* {@code grant_id} request parameter which is defined in the specification.
* If the value of the request parameter is valid, {@link #getGrantSubject()}
* will return the subject of the user who has given the grant to the client
* application. Authorization server implementations may use the value
* returned from {@link #getGrantSubject()} in order to determine the user
* to authenticate.
*
*
*
* The user your system will authenticate during the authorization process
* (or has already authenticated) may be different from the user of the
* grant. The first implementer's draft of "Grant Management for OAuth 2.0"
* does not mention anything about the case, so the behavior in the case is
* left to implementations. Authlete will not perform the grant management
* action when the {@code subject} passed to Authlete does not match the
* user of the grant.
*
*
* @return
* The subject of the user who has given the grant.
*
* @see Grant Management for OAuth 2.0
*
* @since 3.1
*/
public String getGrantSubject()
{
return grantSubject;
}
/**
* Set the subject of the user who has given the grant which is identified
* by the {@code grant_id} request parameter.
*
*
* Authlete 2.3 and newer versions support Grant Management
* for OAuth 2.0. A backchannel authentication request may contain a
* {@code grant_id} request parameter which is defined in the specification.
* If the value of the request parameter is valid, {@link #getGrantSubject()}
* will return the subject of the user who has given the grant to the client
* application. Authorization server implementations may use the value
* returned from {@link #getGrantSubject()} in order to determine the user
* to authenticate.
*
*
*
* The user your system will authenticate during the authorization process
* (or has already authenticated) may be different from the user of the
* grant. The first implementer's draft of "Grant Management for OAuth 2.0"
* does not mention anything about the case, so the behavior in the case is
* left to implementations. Authlete will not perform the grant management
* action when the {@code subject} passed to Authlete does not match the
* user of the grant.
*
*
* @param subject
* The subject of the user who has given the grant.
*
* @return
* {@code this} object.
*
* @see Grant Management for OAuth 2.0
*
* @since 3.1
*/
public BackchannelAuthenticationResponse setGrantSubject(String subject)
{
this.grantSubject = subject;
return this;
}
/**
* Get the content of the grant which is identified by the {@code grant_id}
* request parameter.
*
*
* The user your system will authenticate during the authorization process
* (or has already authenticated) may be different from the user of the grant.
* Be careful when your system displays the content of the grant.
*
*
* @return
* The content of the grant.
*
* @see Grant Management for OAuth 2.0
*
* @since 3.1
*/
public Grant getGrant()
{
return grant;
}
/**
* Set the content of the grant which is identified by the {@code grant_id}
* request parameter.
*
*
* The user your system will authenticate during the authorization process
* (or has already authenticated) may be different from the user of the grant.
* Be careful when your system displays the content of the grant.
*
*
* @param grant
* The content of the grant.
*
* @return
* {@code this} object.
*
* @see Grant Management for OAuth 2.0
*
* @since 3.1
*/
public BackchannelAuthenticationResponse setGrant(Grant grant)
{
this.grant = grant;
return this;
}
/**
* Get the attributes of the service that the client application belongs to.
*
*
* This property is available since Authlete 2.2.
*
*
* @return
* The attributes of the service.
*
* @since 2.88
*/
public Pair[] getServiceAttributes()
{
return serviceAttributes;
}
/**
* Set the attributes of the service that the client application belongs to.
*
*
* This property is available since Authlete 2.2.
*
*
* @param attributes
* The attributes of the service.
*
* @return
* {@code this} object.
*
* @since 2.88
*/
public BackchannelAuthenticationResponse setServiceAttributes(Pair[] attributes)
{
this.serviceAttributes = attributes;
return this;
}
/**
* Get the attributes of the client.
*
*
* This property is available since Authlete 2.2.
*
*
* @return
* The attributes of the client.
*
* @since 2.88
*/
public Pair[] getClientAttributes()
{
return clientAttributes;
}
/**
* Set the attributes of the client.
*
*
* This property is available since Authlete 2.2.
*
*
* @param attributes
* The attributes of the client.
*
* @return
* {@code this} object.
*
* @since 2.88
*/
public BackchannelAuthenticationResponse setClientAttributes(Pair[] attributes)
{
this.clientAttributes = attributes;
return this;
}
/**
* Get the warnings raised during processing the backchannel authentication
* request.
*
* @return
* Warnings. This may be {@code null}.
*/
public String[] getWarnings()
{
return warnings;
}
/**
* Set the warnings raised during processing the backchannel authentication
* request.
*
* @param warnings
* Warnings.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setWarnings(String[] warnings)
{
this.warnings = warnings;
return this;
}
/**
* Get the ticket that is necessary for the implementation of the
* backchannel authentication endpoint to call
* {@code /api/backchannel/authentication/*} API.
*
* @return
* The ticket issued from {@code /api/backchannel/authentication}
* API.
*/
public String getTicket()
{
return ticket;
}
/**
* Set the ticket that is necessary for the implementation of the
* backchannel authentication endpoint to call
* {@code /api/backchannel/authentication/*} API.
*
* @param ticket
* The ticket issued from {@code /api/backchannel/authentication}
* API.
*
* @return
* {@code this} object.
*/
public BackchannelAuthenticationResponse setTicket(String ticket)
{
this.ticket = ticket;
return this;
}
}