java.lang.Object
- com.authlete.common.dto.DeviceCompleteRequest

All Implemented Interfaces:

Serializable
```
public class DeviceCompleteRequest
extends Object
implements Serializable
```
Request to Authlete's /api/device/complete API.
In the device flow, an end-user accesses the verification endpoint of the authorization server where she interacts with the verification endpoint and inputs a user code. The verification endpoint checks if the user code is valid and then asks the end-user whether she approves or rejects the authorization request which the user code represents.

After the authorization server receives the decision of the end-user, it should call Authlete's /api/device/complete API to tell Authlete the decision.

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. The API will update the database record so that /api/auth/token API can generate an access token later.

If the scope parameter of the device authorization request included the openid scope, an ID token is generated. In this case, sub, authTime, acr and claims request parameters in the API call to /api/device/complete affect the ID token.

When the authorization server receives the decision of the end-user and it indicates that she has rejected to give authorization to the client, the authorization server should call the API with result=ACCESS_DENIED. In this case, the API will update the database record so that the /api/auth/token API can generate an error response later. If errorDescription and errorUri request parameters are given to the /api/device/complete API, they will be used as the values of error_description and error_uri response parameters in the error response from the token endpoint.

When the authorization server could not get decision from the end-user 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 response parameter instead of access_denied.

Since:

2.42

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class Description

static class DeviceCompleteRequest.Result
Types of results of end-user authentication and authorization.

Constructor Summary

Constructors
Constructor Description

DeviceCompleteRequest()

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`long`	`getAccessTokenDuration()`	Get the duration of the access token that may be issued as a result of the Authlete API call.
`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[]`	`getConsentedClaims()`	Get the claims that the user has consented for the client application to know.
`String`	`getErrorDescription()`	Get the description of the error.
`URI`	`getErrorUri()`	Get the URI of a document which describes the error in detail.
`String`	`getIdtHeaderParams()`	Get JSON that represents additional JWS header parameters for the ID token that may be issued from the token endpoint.
`String`	`getIdTokenAudType()`	Get the type of the `aud` claim of the ID token being issued.
`String`	`getJwtAtClaims()`	Get the additional claims in JSON object format that are added to the payload part of the JWT access token.
`Property[]`	`getProperties()`	Get the extra properties associated with the access token that will be issued.
`long`	`getRefreshTokenDuration()`	Get the duration of the refresh token that may be issued as a result of the Authlete API call.
`DeviceCompleteRequest.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`	`getUserCode()`	Get the user code input by the end-user.
`DeviceCompleteRequest`	`setAccessTokenDuration(long duration)`	Set the duration of the access token that may be issued as a result of the Authlete API call.
`DeviceCompleteRequest`	`setAcr(String acr)`	Set the reference of the authentication context class which the end-user authentication satisfied.
`DeviceCompleteRequest`	`setAuthTime(long authTime)`	Set the time at which the end-user was authenticated.
`DeviceCompleteRequest`	`setClaims(String claims)`	Set additional claims which will be embedded in the ID token.
`DeviceCompleteRequest`	`setClaims(Map<String,Object> claims)`	Set additional claims which will be embedded in the ID token.
`DeviceCompleteRequest`	`setConsentedClaims(String[] claims)`	Set the claims that the user has consented for the client application to know.
`DeviceCompleteRequest`	`setErrorDescription(String description)`	Set the description of the error.
`DeviceCompleteRequest`	`setErrorUri(URI uri)`	Set the URI of a document which describes the error in detail.
`DeviceCompleteRequest`	`setIdtHeaderParams(String params)`	Set JSON that represents additional JWS header parameters for the ID token that may be issued from the token endpoint.
`DeviceCompleteRequest`	`setIdTokenAudType(String type)`	Set the type of the `aud` claim of the ID token being issued.
`DeviceCompleteRequest`	`setJwtAtClaims(String claims)`	Set the additional claims in JSON object format that are added to the payload part of the JWT access token.
`DeviceCompleteRequest`	`setProperties(Property[] properties)`	Set extra properties associated with the access token that will be issued.
`DeviceCompleteRequest`	`setRefreshTokenDuration(long duration)`	Set the duration of the refresh token that may be issued as a result of the Authlete API call.
`DeviceCompleteRequest`	`setResult(DeviceCompleteRequest.Result result)`	Set the result of end-user authentication and authorization.
`DeviceCompleteRequest`	`setScopes(String[] scopes)`	Set scopes associated with the access token.
`DeviceCompleteRequest`	`setSub(String sub)`	Set the value of the `sub` claim that should be used in the ID token.
`DeviceCompleteRequest`	`setSubject(String subject)`	Set the subject (= unique identifier) of the end-user who has granted authorization to the client application.
`DeviceCompleteRequest`	`setUserCode(String userCode)`	Set the user code input by the end-user.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail
- DeviceCompleteRequest
```
public DeviceCompleteRequest()
```

Method Detail

getUserCode
```
public String getUserCode()
```
Get the user code input by the end-user.

Returns:

The user code.

setUserCode
```
public DeviceCompleteRequest setUserCode(String userCode)
```
Set the user code input by the end-user. This request parameter is mandatory.

Parameters:

userCode - The user code.

Returns:

this object.

getResult
```
public DeviceCompleteRequest.Result getResult()
```
Get the result of end-user authentication and authorization.

Returns:

The result of end-user authentication and authorization.

setResult
```
public DeviceCompleteRequest setResult(DeviceCompleteRequest.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 DeviceCompleteRequest 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.

Since:

2.44

See Also:

getSubject()

setSub
```
public DeviceCompleteRequest 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.

Since:

2.44

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.

Since:

2.44

setAuthTime
```
public DeviceCompleteRequest 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.

Since:

2.44

getAcr
```
public String getAcr()
```
Get the reference of the authentication context class which the end-user authentication satisfied.

Returns:

The authentication context class reference.

Since:

2.44

setAcr
```
public DeviceCompleteRequest 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.

Since:

2.44

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.

Since:

2.44

See Also:

setClaims(String)

setClaims
```
public DeviceCompleteRequest 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.

Since:

2.44

See Also:

OpenID Connect Core 1.0, 5.1. Standard Claims

setClaims
```
public DeviceCompleteRequest 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.

Since:

2.44

getProperties
```
public Property[] getProperties()
```
Get the extra properties associated with the access token that will be issued.

Returns:

Extra properties.

setProperties
```
public DeviceCompleteRequest setProperties(Property[] properties)
```
Set extra properties associated with the access token that will be issued.
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 device authorization request.

Returns:

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

setScopes
```
public DeviceCompleteRequest setScopes(String[] scopes)
```
Set scopes associated with the access token. If null (the default value) is set, the scopes specified in the original device authorization 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.

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.

getIdtHeaderParams
```
public String getIdtHeaderParams()
```
Get JSON that represents additional JWS header parameters for the ID token that may be issued from the token endpoint.

Returns:

JSON that represents additional JWS header parameters for the ID token.

Since:

2.79

setIdtHeaderParams
```
public DeviceCompleteRequest setIdtHeaderParams(String params)
```
Set JSON that represents additional JWS header parameters for the ID token that may be issued from the token endpoint.

Parameters:

params - JSON that represents additional JWS header parameters for the ID token.

Returns:

this object.

Since:

2.79

getConsentedClaims
```
public String[] getConsentedClaims()
```
Get the claims that the user has consented for the client application to know.
See the description of setConsentedClaims(String[]) for details.

Returns:

Consented claims.

Since:

3.7

setConsentedClaims
```
public DeviceCompleteRequest setConsentedClaims(String[] claims)
```
Set the claims that the user has consented for the client application to know.
If the claims request parameter holds JSON, Authlete extracts claims from the JSON and embeds them in an ID token (cf. setClaims(String)). However, the claims are not necessarily identical to the set of claims that the user has actually consented for the client application to know.

For example, if the user has allowed the profile scope to be tied to an access token being issued, it technically means that the user has consented for the client application to know the following claims based on the mapping defined in OpenID Connect Core 1.0 Section 5.4. Requesting Claims using Scope Values: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale and updated_at. However, JSON of the claims request parameter does not necessarily include all the claims. It may be simply because the authorization server does not support other claims or because the authorization server intends to return requested claims from the UserInfo Endpoint instead of embedding them in an ID token, or for some other reasons. Therefore, Authlete does not assume that the claims in the JSON of the claims request parameter represent the complete set of consented claims.

This consentedClaims request parameter (supported from Authlete 2.3) can be used to convey the exact set of consented claims to Authlete. Authlete saves the information into its database and makes them referrable in responses from the /api/auth/introspection API and the /api/auth/userinfo API.

In addition, the information conveyed via this consentedClaims request parameter is used to compute the exact value of the claims parameter in responses from the Grant Management Endpoint, which is defined in Grant Management for OAuth 2.0.

When this request parameter is missing or its value is empty, Authlete computes the set of consented claims from the consented scopes (e.g. profile) and the claims in the JSON of the claims request parameter although Authlete knows the possibility that the computed set may be different from the actual set of consented claims. Especially, the computed set may not include claims that the authorization server returns from the UserInfo Endpoint. Therefore, if you want to control the exact set of consented claims, utilize this request parameter.

Parameters:

claims - Consented claims.

Returns:

this object.

Since:

3.7

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 DeviceCompleteRequest 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 DeviceCompleteRequest 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.

getJwtAtClaims
```
public String getJwtAtClaims()
```
Get the additional claims in JSON object format that are added to the payload part of the JWT access token.
This request parameter has a meaning only when the format of access tokens issued by this service is JWT. In other words, it has a meaning only when the accessTokenSignAlg property of the Service holds a non-null value. See the description of the getAccessTokenSignAlg() method for details.

Returns:

Additional claims that are added to the payload part of the JWT access token.

Since:

3.23

setJwtAtClaims
```
public DeviceCompleteRequest setJwtAtClaims(String claims)
```
Set the additional claims in JSON object format that are added to the payload part of the JWT access token.
This request parameter has a meaning only when the format of access tokens issued by this service is JWT. In other words, it has a meaning only when the accessTokenSignAlg property of the Service holds a non-null value. See the description of the getAccessTokenSignAlg() method for details.

Parameters:

claims - Additional claims that are added to the payload part of the JWT access token.

Returns:

this object.

Since:

3.23

getAccessTokenDuration
```
public long getAccessTokenDuration()
```
Get the duration of the access token that may be issued as a result of the Authlete API call.
When this request parameter holds a positive integer, it is used as the duration of the access token. In other cases, this request parameter is ignored.

Returns:

The duration of the access token in seconds.

Since:

4.8, Authlete 2.3.20, Authlete 3.0

setAccessTokenDuration
```
public DeviceCompleteRequest setAccessTokenDuration(long duration)
```
Set the duration of the access token that may be issued as a result of the Authlete API call.
When this request parameter holds a positive integer, it is used as the duration of the access token. In other cases, this request parameter is ignored.

Parameters:

duration - The duration of the access token in seconds.

Returns:

this request parameter.

Since:

4.8, Authlete 2.3.20, Authlete 3.0

getRefreshTokenDuration
```
public long getRefreshTokenDuration()
```
Get the duration of the refresh token that may be issued as a result of the Authlete API call.
When this request parameter holds a positive integer, it is used as the duration of the refresh token. In other cases, this request parameter is ignored.

Returns:

The duration of the refresh token in seconds.

Since:

4.8, Authlete 2.3.20, Authlete 3.0

setRefreshTokenDuration
```
public DeviceCompleteRequest setRefreshTokenDuration(long duration)
```
Set the duration of the refresh token that may be issued as a result of the Authlete API call.
When this request parameter holds a positive integer, it is used as the duration of the refresh token. In other cases, this request parameter is ignored.

Parameters:

duration - The duration of the refresh token in seconds.

Returns:

this object.

Since:

4.8, Authlete 2.3.20, Authlete 3.0

getIdTokenAudType

public String getIdTokenAudType()

Get the type of the aud claim of the ID token being issued. Valid values are as follows.

Value Description

"array" The type of the aud claim is always an array of strings.

"string" The type of the aud claim is always a single string.

null The type of the aud claim remains the same as before.

This request parameter takes precedence over the idTokenAudType property of Service (cf. Service.getIdTokenAudType()).

Returns:: The type of the aud claim in ID tokens.
Since:: 3.57, Authlete 2.3.3

setIdTokenAudType

public DeviceCompleteRequest setIdTokenAudType(String type)

Set the type of the aud claim of the ID token being issued. Valid values are as follows.

Value Description

"array" The type of the aud claim is always an array of strings.

"string" The type of the aud claim is always a single string.

null The type of the aud claim remains the same as before.

This request parameter takes precedence over the idTokenAudType property of Service (cf. Service.getIdTokenAudType()).

Parameters:: type - The type of the aud claim in ID tokens.
Returns:: this object.
Since:: 3.57, Authlete 2.3.3

Value	Description
`"array"`	The type of the `aud` claim is always an array of strings.
`"string"`	The type of the `aud` claim is always a single string.
null	The type of the `aud` claim remains the same as before.

Class DeviceCompleteRequest

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DeviceCompleteRequest

Method Detail

getUserCode

setUserCode

getResult

setResult

getSubject

setSubject

getSub

setSub

getAuthTime

setAuthTime

getAcr

setAcr

getClaims

setClaims

setClaims

getProperties

setProperties

getScopes

setScopes

getIdtHeaderParams

setIdtHeaderParams

getConsentedClaims

setConsentedClaims

getErrorDescription

setErrorDescription

getErrorUri

setErrorUri

getJwtAtClaims

setJwtAtClaims

getAccessTokenDuration

setAccessTokenDuration

getRefreshTokenDuration

setRefreshTokenDuration

getIdTokenAudType

setIdTokenAudType