com.authlete.common.dto

Class BackchannelAuthenticationCompleteRequest

java.lang.Object

com.authlete.common.dto.BackchannelAuthenticationCompleteRequest

All Implemented Interfaces:

Serializable

public class BackchannelAuthenticationCompleteRequest
extends Object
implements Serializable

Request to Authlete's /api/backchannel/authentication/complete API.

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 /api/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 /api/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 /api/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.

Since:

2.32

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BackchannelAuthenticationCompleteRequest.Result Types of results of end-user authentication and authorization.

Constructor Summary

Constructors

Constructor and Description
BackchannelAuthenticationCompleteRequest()

Method Summary

Modifier and Type	Method and Description
String	getAcr() Get the reference of the authentication context class which the end-user authentication satisfied.
long	getAuthTime() Get the time at which the end-user was authenticated.
String	getClaims() Get additional claims which will be embedded in the ID token.
String	getErrorDescription() Get the description of the error.
URI	getErrorUri() Get the URI of a document which describes the error in detail.
Property[]	getProperties() Get the extra properties associated with the access token.
BackchannelAuthenticationCompleteRequest.Result	getResult() Get the result of end-user authentication and authorization.
String[]	getScopes() Get scopes associated with the access token.
String	getSub() Get the value of the sub claim that should be used in the ID token.
String	getSubject() Get the subject (= unique identifier) of the end-user who has granted authorization to the client application.
String	getTicket() Get the ticket which is necessary to call Authlete's /api/backchannel/authentication/complete API.
BackchannelAuthenticationCompleteRequest	setAcr(String acr) Set the reference of the authentication context class which the end-user authentication satisfied.
BackchannelAuthenticationCompleteRequest	setAuthTime(long authTime) Set the time at which the end-user was authenticated.
BackchannelAuthenticationCompleteRequest	setClaims(Map<String,Object> claims) Set additional claims which will be embedded in the ID token.
BackchannelAuthenticationCompleteRequest	setClaims(String claims) Set additional claims which will be embedded in the ID token.
BackchannelAuthenticationCompleteRequest	setErrorDescription(String description) Set the description of the error.
BackchannelAuthenticationCompleteRequest	setErrorUri(URI uri) Set the URI of a document which describes the error in detail.
BackchannelAuthenticationCompleteRequest	setProperties(Property[] properties) Set extra properties associated with the access token.
BackchannelAuthenticationCompleteRequest	setResult(BackchannelAuthenticationCompleteRequest.Result result) Set the result of end-user authentication and authorization.
BackchannelAuthenticationCompleteRequest	setScopes(String[] scopes) Set scopes associated with the access token.
BackchannelAuthenticationCompleteRequest	setSub(String sub) Set the value of the sub claim that should be used in the ID token.
BackchannelAuthenticationCompleteRequest	setSubject(String subject) Set the subject (= unique identifier) of the end-user who has granted authorization to the client application.
BackchannelAuthenticationCompleteRequest	setTicket(String ticket) Set the ticket which is necessary to call Authlete's /api/backchannel/authentication/complete API.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BackchannelAuthenticationCompleteRequest

public BackchannelAuthenticationCompleteRequest()

Method Detail

getTicket

public String getTicket()

Get the ticket which is necessary to call Authlete's /api/backchannel/authentication/complete API.

Returns:

The ticket.

setTicket

public BackchannelAuthenticationCompleteRequest setTicket(String ticket)

Set the ticket which is necessary to call Authlete's /api/backchannel/authentication/complete API. This request parameter is mandatory.

Parameters:

ticket - The ticket previously issued by Authlete's /api/backchannel/authentication API.

Returns:

this object.

getResult

public BackchannelAuthenticationCompleteRequest.Result getResult()

Get the result of end-user authentication and authorization.

Returns:

The result of end-user authentication and authorization.

setResult

public BackchannelAuthenticationCompleteRequest setResult(BackchannelAuthenticationCompleteRequest.Result result)

Set the result of end-user authentication and authorization. This request parameter is mandatory.

Parameters:

result - The result of end-user authentication and authorization.

Returns:

this object.

getSubject

public String getSubject()

Get the subject (= unique identifier) of the end-user who has granted authorization to the client application.

This subject property is used as the value of the subject associated with the access token and as the value of the sub claim in the ID token.

Note that, if getSub() returns a non-empty value, it is used as the value of the sub claim in the ID token. However, even in the case, the value of the subject associated with the access token is still the value of this subject property.

Returns:

The subject (= unique identifier) of the end-user.

See Also:

getSub()

setSubject

public BackchannelAuthenticationCompleteRequest setSubject(String subject)

Set the subject (= unique identifier) of the end-user who has granted authorization to the client application. This request parameter is mandatory when getResult() returns AUTHORIZED.

This subject property is used as the value of the subject associated with the access token and as the value of the sub claim in the ID token.

Note that, if getSub() returns a non-empty value, it is used as the value of the sub claim in the ID token. However, even in the case, the value of the subject associated with the access token is still the value set by this method.

Parameters:

subject - The subject (= unique identifier) of the end-user.

Returns:

this object.

See Also:

setSub(String)

getSub

public String getSub()

Get the value of the sub claim that should be used in the ID token. If this method returns null or its value is empty, the value returned by getSubject() is used as the value of the sub claim. The main purpose of this sub property is to hide the actual value of the subject from client applications.

Note that the value of the subject request parameter is used as the value of the subject associated with the access token regardless of whether this sub property is a non-empty value or not. In other words, this sub property affects only the sub claim in the ID token.

Returns:

The value of the sub claim.

See Also:

getSubject()

setSub

public BackchannelAuthenticationCompleteRequest setSub(String sub)

Set the value of the sub claim that should be used in the ID token. If this method returns null or its value is empty, the value returned by getSubject() is used as the value of the sub claim. The main purpose of this sub property is to hide the actual value of the subject from client applications.

Note that the value of the subject request parameter is used as the value of the subject associated with the access token regardless of whether this sub property is a non-empty value or not. In other words, this sub property affects only the sub claim in the ID token.

Parameters:

sub - The value of the sub claim.

Returns:

this object.

See Also:

setSubject(String)

getAuthTime

public long getAuthTime()

Get the time at which the end-user was authenticated.

Returns:

The time at which the end-user was authenticated. It is the number of seconds since 1970-01-01.

setAuthTime

public BackchannelAuthenticationCompleteRequest setAuthTime(long authTime)

Set the time at which the end-user was authenticated. When this request parameter holds a positive number, the auth_time claim will be embedded in the ID token.

Parameters:

authTime - The time at which the end-user was authenticated. It is the number of seconds since 1970-01-01.

Returns:

this object.

getAcr

public String getAcr()

Get the reference of the authentication context class which the end-user authentication satisfied.

Returns:

The authentication context class reference.

setAcr

public BackchannelAuthenticationCompleteRequest setAcr(String acr)

Set the reference of the authentication context class which the end-user authentication satisfied. When this request parameter holds a non-null value, the acr claim will be embedded in the ID token.

Parameters:

acr - The authentication context class reference.

Returns:

this object.

getClaims

public String getClaims()

Get additional claims which will be embedded in the ID token.

Returns:

Additional claims in JSON format which will be embedded in the ID token. See the description of setClaims(String) for details about the format.

See Also:

setClaims(String)

setClaims

public BackchannelAuthenticationCompleteRequest setClaims(String claims)

Set additional claims which will be embedded in the ID token.

The authorization server implementation is required to retrieve values of requested claims of the end-user from its database and format them in JSON format.

For example, if "given_name" claim, "family_name" claim and "email" claim are requested, the authorization server implementation should generate a JSON object like the following:

 {
   "given_name": "Takahiko",
   "family_name": "Kawasaki",
   "email": "takahiko.kawasaki@example.com"
 }
 

and set its string representation by this method.

See OpenID Connect Core 1.0, 5.1. Standard Claims for further details about the format.

Parameters:

claims - Additional claims in JSON format.

Returns:

this object.

See Also:

OpenID Connect Core 1.0, 5.1. Standard Claims

setClaims

public BackchannelAuthenticationCompleteRequest setClaims(Map<String,Object> claims)

Set additional claims which will be embedded in the ID token.

The argument is converted into a JSON string and passed to setClaims(String) method.

Parameters:

claims - Additional claims. Keys are claim names.

Returns:

this object.

getProperties

public Property[] getProperties()

Get the extra properties associated with the access token.

Returns:

Extra properties.

setProperties

public BackchannelAuthenticationCompleteRequest setProperties(Property[] properties)

Set extra properties associated with the access token.

Keys of extra properties will be used as labels of top-level entries in a JSON response returned from the authorization server. An example is example_parameter, which you can find in 5.1. Successful Response in RFC 6749. The following code snippet is an example to set one extra property having example_parameter as its key and example_value as its value.

 Property[] properties = { new Property("example_parameter", "example_value") };
 request.setProperties(properties);
 

Note that there is an upper limit on the total size of extra properties. On Authlete side, the properties will be (1) converted to a multidimensional string array, (2) converted to JSON, (3) encrypted by AES/CBC/PKCS5Padding, (4) encoded by base64url, and then stored into the database. The length of the resultant string must not exceed 65,535 in bytes. This is the upper limit, but we think it is big enough.

Parameters:

properties - Extra properties.

Returns:

this object.

getScopes

public String[] getScopes()

Get scopes associated with the access token. If this method returns a non-null value, the set of scopes will be used instead of the scopes specified in the original backchannel authentication request.

Returns:

Scopes to replace the scopes specified in the original backchannel authentication request with. When null is returned from this method, replacement is not performed.

setScopes

public BackchannelAuthenticationCompleteRequest setScopes(String[] scopes)

Set scopes associated with the access token. If null (the default value) is set, the scopes specified in the original backchannel authentication request are used. In other cases, the scopes given to this method will replace the original scopes contained in the original request.

Even scopes that are not included in the original request can be included.

Note that because the CIBA specification requires "openid" as a mandatory scope, "openid" should be always included.

Parameters:

scopes - Scopes associated with the access token. If a non-null value is set, the original scopes requested by the client application are replaced.

Returns:

this object.

getErrorDescription

public String getErrorDescription()

Get the description of the error. This corresponds to the error_description property in the response to the client.

Returns:

The description of the error.

setErrorDescription

public BackchannelAuthenticationCompleteRequest setErrorDescription(String description)

Set the description of the error. This corresponds to the error_description property in the response to the client.

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.

Parameters:

description - The description of the error.

Returns:

this object.

getErrorUri

public URI getErrorUri()

Get the URI of a document which describes the error in detail. This corresponds to the error_uri property in the response to the client.

Returns:

The URI of a document which describes the error in detail.

setErrorUri

public BackchannelAuthenticationCompleteRequest setErrorUri(URI uri)

Set the URI of a document which describes the error in detail. This corresponds to the error_uri property in the response to the client.

If this optional request parameter is given, its value is used as the value of the error_uri property, but it is used only when the result is not AUTHORIZED.

Parameters:

uri - The URI of a document which describes the error in detail.

Returns:

this object.