Documentation

DeviceCompleteRequest implements ArrayCopyable, Arrayable, Jsonable Uses ArrayTrait, JsonTrait

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

In the device flow (RFC 8628), 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 the /api/device/complete API 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.

Interfaces, Classes and Traits

ArrayCopyable: Interface to declare instances can be converted into/from arrays.
Arrayable: Interface to declare that instances can be converted into an array.
Jsonable: Interface to declare that instances can be converted into JSON strings.

copyFromArray() : mixed: Copy the content of the given array into this object.
copyToArray() : mixed: Copy the content of this object into the given array.
fromArray() : static: Convert an array into an instance of this class.
fromJson() : static: Convert a JSON string into an instance of this class.
getAcr() : string: Get the reference of the authentication context class which the end-user authentication satisfied. When this property holds a non-null value, the value will be used as the value of the `acr` claim in the ID token.
getAuthTime() : int|string: Get the time when the authentication of the end-user occurred.
getClaims() : string: Get additional claims which will be embedded in the ID token.
getErrorDescription() : string: Get the description of the error. This corresponds to the `error_description` property in the response to the client.
getErrorUri() : string: 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.
getIdtHeaderParams() : string: Get JSON that represents additional JWS header parameters for the ID token that may be issued from the token endpoint.
getProperties() : array<string|int, Property>: Get the extra properties associated with the access token that will be issued.
getResult() : DeviceCompleteResult: Get the result of end-user authentication and authorization.
getScopes() : array<string|int, string>: Get scopes associated with the access token. If this property holds a non-null value, the set of scopes will be used instead of the scopes specified in the original device authorization request.
getSub() : string: Get the value of the `sub` claim that should be used in the ID token.
getSubject() : string: Get the subject (= unique identifier) of the end-user who has granted authorization to the client application. This request parameter is mandatory when the `result` property holds `DeviceCompleteResult::$AUTHORIZED`.
getUserCode() : string: Get the user code input by the end-user.
setAcr() : DeviceCompleteRequest: Set the reference of the authentication context class which the end-user authentication satisfied. When this property holds a non-null value, the value will be used as the value of the `acr` claim in the ID token.
setAuthTime() : DeviceCompleteRequest: Set the time when the authentication of the end-user occurred.
setClaims() : DeviceCompleteRequest: Set additional claims which will be embedded in the ID token.
setErrorDescription() : DeviceCompleteRequest: Set the description of the error. This corresponds to the `error_description` property in the response to the client.
setErrorUri() : DeviceCompleteRequest: 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.
setIdtHeaderParams() : DeviceCompleteRequest: Set JSON that represents additional JWS header parameters for the ID token that may be issued from the token endpoint.
setProperties() : DeviceCompleteRequest: Set the extra properties associated with the access token that will be issued.
setResult() : DeviceCompleteRequest: Set the result of end-user authentication and authorization.
setScopes() : DeviceCompleteRequest: Set scopes associated with the access token. If this property holds a non-null value, the set of scopes will be used instead of the scopes specified in the original device authorization request.
setSub() : DeviceCompleteRequest: Set the value of the `sub` claim that should be used in the ID token.
setSubject() : DeviceCompleteRequest: Set the subject (= unique identifier) of the end-user who has granted authorization to the client application. This request parameter is mandatory when the `result` property holds `DeviceCompleteResult::$AUTHORIZED`.
setUserCode() : DeviceCompleteRequest: Set the user code input by the end-user.
toArray() : array<string|int, mixed>: Convert this object into an array.
toJson() : string: Convert this object into a JSON string.

copyFromArray()

Copy the content of the given array into this object.


    public
                copyFromArray(array<string|int, mixed> &$array) : mixed

Parameters

$array : array<string|int, mixed>

Return values

mixed —

copyToArray()

Copy the content of this object into the given array.


    public
                copyToArray(array<string|int, mixed> &$array) : mixed

Parameters

$array : array<string|int, mixed>

Return values

mixed —

fromArray()

Convert an array into an instance of this class.


    public
            static    fromArray([array<string|int, mixed> $array = null ]) : static

This static function returns a new instance of this class. If $array is null, null is returned.

Parameters

$array : array<string|int, mixed> = null: An array

Return values

static —

An instance of this class.

fromJson()

Convert a JSON string into an instance of this class.


    public
            static    fromJson(string $json) : static

This static function returns a new instance of this class. If $json is null or the type of $json is not string, null is returned.

Parameters

$json : string: A JSON string.

Return values

static —

An instance of this class.

getAcr()

Get the reference of the authentication context class which the end-user authentication satisfied. When this property holds a non-null value, the value will be used as the value of the `acr` claim in the ID token.


    public
                getAcr() : string

Return values

string —

The authentication context class reference.

getAuthTime()

Get the time when the authentication of the end-user occurred.


    public
                getAuthTime() : int|string

The value represents the elapsed time since the Unix epoch (1970-Jan-1) in seconds.

Return values

int|string —

The time when the authentication of the end-user occurred.

getClaims()

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


    public
                getClaims() : string

Return values

string —

Additional claims in JSON format which will be embedded in the ID token.

getErrorDescription()

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


    public
                getErrorDescription() : string

Return values

string —

The description of the error.

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.


    public
                getErrorUri() : string

Return values

string —

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

getIdtHeaderParams()

Get JSON that represents additional JWS header parameters for the ID token that may be issued from the token endpoint.


    public
                getIdtHeaderParams() : string

Return values

string —

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

getProperties()

Get the extra properties associated with the access token that will be issued.


    public
                getProperties() : array<string|int, Property>

Return values

array<string|int, Property> —

Extra properties.

getResult()

Get the result of end-user authentication and authorization.


    public
                getResult() : DeviceCompleteResult

Return values

DeviceCompleteResult —

The result of end-user authentication and authorization.

getScopes()

Get scopes associated with the access token. If this property holds a non-null value, the set of scopes will be used instead of the scopes specified in the original device authorization request.


    public
                getScopes() : array<string|int, string>

Return values

array<string|int, string> —

Scopes to replace the scopes specified in the original device authorization request with. If this property holds null, replacement is not performed.

getSub()

Get the value of the `sub` claim that should be used in the ID token.


    public
                getSub() : string

If this property holds null or its value is empty, the value held by 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 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.

Return values

string —

The value of the sub claim.

getSubject()

Get the subject (= unique identifier) of the end-user who has granted authorization to the client application. This request parameter is mandatory when the `result` property holds `DeviceCompleteResult::$AUTHORIZED`.


    public
                getSubject() : string

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 the sub property holds a non-null 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.

Return values

string —

The subject of the end-user.

getUserCode()

Get the user code input by the end-user.


    public
                getUserCode() : string

Return values

string —

The user code.

setAcr()

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


    public
                setAcr(string $acr) : DeviceCompleteRequest

Parameters

$acr : string: The authentication context class reference.

Return values

DeviceCompleteRequest —

$this object.

setAuthTime()

Set the time when the authentication of the end-user occurred.


    public
                setAuthTime(int|string $authTime) : DeviceCompleteRequest

The value should represent the elapsed time since the Unix epoch (1970-Jan-1) in seconds.

Parameters

$authTime : int|string: The time when the authentication of the end-user occurred.

Return values

DeviceCompleteRequest —

$this object.

setClaims()

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


    public
                setClaims(string $claims) : DeviceCompleteRequest

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 5.1. Standard Claims in OpenID Connect Core 1.0 for details about the format.

Parameters

$claims : string: Additional claims in JSON format which will be embedded in the ID token.

Return values

DeviceCompleteRequest —

$this object.

setErrorDescription()

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


    public
                setErrorDescription(string $description) : DeviceCompleteRequest

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 : string: The description of the error.

Return values

DeviceCompleteRequest —

$this object.

setErrorUri()

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.


    public
                setErrorUri(string $uri) : DeviceCompleteRequest

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 : string: The URI of a document which describes the error in detail.

Return values

DeviceCompleteRequest —

$this object.

setIdtHeaderParams()

Set JSON that represents additional JWS header parameters for the ID token that may be issued from the token endpoint.


    public
                setIdtHeaderParams(string $params) : DeviceCompleteRequest

Parameters

$params : string: JSON that represents additional JWS header parameters for the ID token.

Return values

DeviceCompleteRequest —

$this object.

setProperties()

Set the extra properties associated with the access token that will be issued.


    public
                setProperties([array<string|int, mixed> $properties = null ]) : DeviceCompleteRequest

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.

$properties = array(
    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 : array<string|int, mixed> = null: Extra properties.

Return values

DeviceCompleteRequest —

$this object.

setResult()

Set the result of end-user authentication and authorization.


    public
                setResult([DeviceCompleteResult $result = null ]) : DeviceCompleteRequest

This request parameter is mandatory.

Parameters

$result : DeviceCompleteResult = null: The result of end-user authentication and authorization.

Return values

DeviceCompleteRequest —

$this object.

setScopes()

Set scopes associated with the access token. If this property holds a non-null value, the set of scopes will be used instead of the scopes specified in the original device authorization request.


    public
                setScopes([array<string|int, mixed> $scopes = null ]) : DeviceCompleteRequest

Scopes that are not included in the original request can be included.

Parameters

$scopes : array<string|int, mixed> = null: Scopes to replace the scopes specified in the original device authorization request with. If this property holds null, replacement is not performed.

Return values

DeviceCompleteRequest —

$this object.

setSub()

Set the value of the `sub` claim that should be used in the ID token.


    public
                setSub(string $sub) : DeviceCompleteRequest

Parameters

$sub : string: The value of the sub claim.

Return values

DeviceCompleteRequest —

$this object.

setSubject()

Set the subject (= unique identifier) of the end-user who has granted authorization to the client application. This request parameter is mandatory when the `result` property holds `DeviceCompleteResult::$AUTHORIZED`.


    public
                setSubject(string $subject) : DeviceCompleteRequest

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.

Parameters

$subject : string: The subject of the end-user.

Return values

DeviceCompleteRequest —

$this object.

setUserCode()

Set the user code input by the end-user.


    public
                setUserCode(string $code) : DeviceCompleteRequest

This request parameter is mandatory.

Parameters

$code : string: The user code.

Return values

DeviceCompleteRequest —

$this object.

toArray()

Convert this object into an array.


    public
                toArray() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array.

toJson()

Convert this object into a JSON string.


    public
                toJson(int $options) : string

Parameters

$options : int: Options passed to json_encode(). This parameter is optional and its default value is 0.

Return values

string —

A JSON string.

DeviceCompleteRequest implements ArrayCopyable, Arrayable, Jsonable Uses ArrayTrait, JsonTrait

Tags

Interfaces, Classes and Traits

Table of Contents

Methods

copyFromArray()

Parameters

Return values

copyToArray()

Parameters

Return values

fromArray()

Parameters

Return values

fromJson()

Parameters

Return values

getAcr()

Return values

getAuthTime()

Return values

getClaims()

Return values

getErrorDescription()

Return values

getErrorUri()

Return values

getIdtHeaderParams()

Tags

Return values

getProperties()

Return values

getResult()

Return values

getScopes()

Return values

getSub()

Return values

getSubject()

Return values

getUserCode()

Return values

setAcr()

Parameters

Return values

setAuthTime()

Parameters

Return values

setClaims()

Parameters

Return values

setErrorDescription()

Parameters

Return values

setErrorUri()

Parameters

Return values

setIdtHeaderParams()

Parameters

Tags

Return values

setProperties()

Parameters

Return values

setResult()

Parameters

Return values

setScopes()

Parameters

Return values

setSub()

Parameters

Return values

setSubject()

Parameters

Return values

setUserCode()

Parameters

Return values

toArray()