Request to Authlete's /api/device/complete API. More...

Properties
string	UserCode `[get, set]`
	The user code input by the end-user. More...

DeviceCompleteResult	Result `[get, set]`
	The result of end-user authentication and authorization. More...

string	Subject `[get, set]`
	The subject (= unique identifier) of the end-user who has granted authorization to the client application. This propery must have a non-null value when `Result` is `DeviceCompleteResult.AUTHORIZED`. More...

string	Sub `[get, set]`
	The value of the `"sub"` claim used in the ID token. If this property returns `null` or its value is empty, the value of the `Subject` property 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. More...

long	AuthTime `[get, 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. More...

string	Acr `[get, 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. More...

string	Claims `[get, set]`
	Additional claims which will be embedded in the ID token. More...

Property[]	Properties `[get, set]`
	Extra properties that you want to associate with the access token. This request parameter is optional. More...

string[]	Scopes `[get, set]`
	Scopes that should be 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 set to this property will replace the original scopes contained in the original request. More...

string	IdtHeaderParams `[get, set]`
	JSON that represents additional JWS header parameters for the ID token. More...

string	ErrorDescription `[get, set]`
	The description of the error. This corresponds to the `error_description` property in the response to the client. More...

Uri	ErrorUri `[get, 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. More...

Detailed Description

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 from 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=DeviceCompleteResult.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 and claims request parameters in the API call to /api/device/complete affect the ID token.

When the authorization server received 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=DeviceCompleteResult.ACCESS_DENIED. In this case, the API will update the database record so that /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=DeviceCompleteResult.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 version 1.5.0.

Property Documentation

◆ Acr

string Acr

getset

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.

◆ AuthTime

long AuthTime

getset

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.

The value should be the number of seconds since the Unix epoch (1970-01-01).

◆ Claims

string Claims

getset

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 and set its string representation to this Claims property.

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

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

◆ ErrorDescription

string ErrorDescription

getset

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 DeviceCompleteResult.AUTHORIZED.

To comply with the specification strictly, the description must not include characters outside the set x20-21 / x23-5B / x5D-7E.

◆ ErrorUri

Uri ErrorUri

getset

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 DeviceCompleteResult.AUTHORIZED.

◆ IdtHeaderParams

string IdtHeaderParams

getset

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

◆ Properties

Property [] Properties

getset

Extra properties that you want to associate with the access token. This request parameter is optional.

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.

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

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.

◆ Result

DeviceCompleteResult Result

getset

The result of end-user authentication and authorization.

◆ Scopes

string [] Scopes

getset

Scopes that should be 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 set to this property will replace the original scopes contained in the original request.

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

◆ Sub

string Sub

getset

The value of the "sub" claim used in the ID token. If this property returns null or its value is empty, the value of the Subject property 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 property is used as the value of the subject associated with the access token regardless of whether this Sub property holds a non-empty value or not. In other words, this Sub property affects only the "sub" claim in the ID token.

◆ Subject

string Subject

getset

The subject (= unique identifier) of the end-user who has granted authorization to the client application. This propery must have a non-null value when Result is DeviceCompleteResult.AUTHORIZED.

This 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 the Sub property 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.

◆ UserCode

string UserCode

getset

The user code input by the end-user.

The documentation for this class was generated from the following file:

Authlete/Dto/DeviceCompleteRequest.cs