Documentation

TokenRequest implements ArrayCopyable, Arrayable, Jsonable Uses ArrayTrait, JsonTrait

Request to Authlete's /api/auth/token API.

An entity body of a token request may contain the client ID (client_id) and the client secret (client_secret) along with other request parameters as described in 2.3.1. Client Password of RFC 6749. If client credentials are contained both in the Authorization header and in the entity body, they must be identical. If they do not match, Authlete's /api/auth/token API reports an error. It is not an error of your authorization server implementation but an error of the client application.

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.
getClientCertificate() : string: Get the client certificate from the MTLS of the token request from the client application.
getClientCertificatePath() : array<string|int, string>: Get the certificate path presented by the client during client authentication.
getClientId() : string: Get the client ID extracted from the Authorization header of the token request from the client application.
getClientSecret() : string: Get the client secret extracted from the Authorization header of the token request from the client application.
getDpop() : string: Get the `DPoP` header presented by the client during the request to the token endpoint. This header contains a signed JWT which includes the public key that is paired with the private key used to sign it.
getHtm() : string: Get the HTTP method of the token request. This property is used to validate the `DPoP` header.
getHtu() : string: Get the URL of the token endpoint. This property is used to validate the `DPoP` header.
getParameters() : string: Get the token request parameters which the token endpoint implementation of your authorization server received from the client application.
getProperties() : array<string|int, Property>: Get the properties to be associated with an access token which may be issued as a result of the token request.
setClientCertificate() : TokenRequest: Set the client certificate from the MTLS of the token request from the client application.
setClientCertificatePath() : TokenRequest: Set the certificate path presented by the client during client authentication.
setClientId() : TokenRequest: Set the client ID extracted from the Authorization header of the token request from the client application.
setClientSecret() : TokenRequest: Set the client secret extracted from the Authorization header of the token request from the client application.
setDpop() : TokenRequest: Set the `DPoP` header presented by the client during the request to the token endpoint. This header contains a signed JWT which includes the public key that is paired with the private key used to sign it.
setHtm() : TokenRequest: Set the HTTP method of the token request. This property is used to validate the `DPoP` header.
setHtu() : TokenRequest: Set the URL of the token endpoint. This property is used to validate the `DPoP` header.
setParameters() : TokenRequest: Set the token request parameters which the token endpoint implementation of your authorization server received from the client application.
setProperties() : TokenRequest: Set the properties to be associated with an access token which may be issued as a result of the token request.
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.

getClientCertificate()

Get the client certificate from the MTLS of the token request from the client application.


    public
                getClientCertificate() : string

Return values

string —

The client certificate.

getClientCertificatePath()

Get the certificate path presented by the client during client authentication.


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

Return values

array<string|int, string> —

Certificates in PEM format.

getClientId()

Get the client ID extracted from the Authorization header of the token request from the client application.


    public
                getClientId() : string

Return values

string —

The client ID extracted from the Authorization header.

getClientSecret()

Get the client secret extracted from the Authorization header of the token request from the client application.


    public
                getClientSecret() : string

Return values

string —

The client secret extracted from the Authorization header.

getDpop()

Get the `DPoP` header presented by the client during the request to the token endpoint. This header contains a signed JWT which includes the public key that is paired with the private key used to sign it.


    public
                getDpop() : string

See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.

Return values

string —

The value of the DPoP header.

getHtm()

Get the HTTP method of the token request. This property is used to validate the `DPoP` header.


    public
                getHtm() : string

In normal cases, the value is POST. When this request parameter is omitted, POST is used as the default value.

See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.

Return values

string —

The HTTP method. For example, POST.

getHtu()

Get the URL of the token endpoint. This property is used to validate the `DPoP` header.


    public
                getHtu() : string

If this request parameter is omitted, the tokenEndpoint property of the Service is used as the default value.

See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.

Return values

string —

The URL of the token endpoint.

getParameters()

Get the token request parameters which the token endpoint implementation of your authorization server received from the client application.


    public
                getParameters() : string

Return values

string —

The request parameters of the token request.

getProperties()

Get the properties to be associated with an access token which may be issued as a result of the token request.


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

Return values

array<string|int, Property> —

Properties associated with the access token.

setClientCertificate()

Set the client certificate from the MTLS of the token request from the client application.


    public
                setClientCertificate(string $certificate) : TokenRequest

Parameters

$certificate : string: The client certificate.

Return values

TokenRequest —

$this object.

setClientCertificatePath()

Set the certificate path presented by the client during client authentication.


    public
                setClientCertificatePath([array<string|int, string> $path = null ]) : TokenRequest

Parameters

$path : array<string|int, string> = null: Certificates in PEM format.

Return values

TokenRequest —

$this object.

setClientId()

Set the client ID extracted from the Authorization header of the token request from the client application.


    public
                setClientId(string $clientId) : TokenRequest

If the token endpoint of the authorization server supports Basic Authentication as a means of client authentication, and if the request from the client application contained its client ID in the Authorization header, the value should be extracted from there and set as the value of this request parameter.

Parameters

$clientId : string: The client ID extracted from the Authorization header.

Return values

TokenRequest —

$this object.

setClientSecret()

Set the client secret extracted from the Authorization header of the token request from the client application.


    public
                setClientSecret(string $clientSecret) : TokenRequest

If the token endpoint of the authorization server supports Basic Authentication as a means of client authentication, and if the request from the client application contained its client secret in the Authorization header, the value should be extracted from there and set as the value of this request parameter.

Parameters

$clientSecret : string: The client secret extracted from the Authorization header.

Return values

TokenRequest —

$this object.

setDpop()

Set the `DPoP` header presented by the client during the request to the token endpoint. This header contains a signed JWT which includes the public key that is paired with the private key used to sign it.


    public
                setDpop(string $dpop) : TokenRequest

See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.

Parameters

$dpop : string: The value of the DPoP header.

Return values

TokenRequest —

$this object.

setHtm()

Set the HTTP method of the token request. This property is used to validate the `DPoP` header.


    public
                setHtm(string $htm) : TokenRequest

In normal cases, the value is POST. When this request parameter is omitted, POST is used as the default value.

See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.

Parameters

$htm : string: The HTTP method. For example, POST.

Return values

TokenRequest —

$this object.

setHtu()

Set the URL of the token endpoint. This property is used to validate the `DPoP` header.


    public
                setHtu(string $htu) : TokenRequest

If this request parameter is omitted, the tokenEndpoint property of the Service is used as the default value.

See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.

Parameters

$htu : string: The URL of the token endpoint.

Return values

TokenRequest —

$this object.

setParameters()

Set the token request parameters which the token endpoint implementation of your authorization server received from the client application.


    public
                setParameters(string $parameters) : TokenRequest

The value of this request parameter is the entire entity body (which is formatted in application/x-www-form-urlencoded) of the request from the client application. This request parameter is mandatory.

Parameters

$parameters : string: The request parameters of the token request.

Return values

TokenRequest —

$this object.

setProperties()

Set the properties to be associated with an access token which may be issued as a result of the token request.


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

If the value of the grant_type parameter contained in the token request from the client application is authorization_code, properties set by this request parameter will be added as the extra properties of a newly created access token. The extra properties specified when the authorization code was issued (using AuthorizationIssueRequest::setProperties()) will also be used, but their values will be overwritten if the extra properties set by this request parameter have the same keys. In other words, extra properties contained in this request will be merged into existing extra properties which are associated with the authorization code.

Otherwise, if the value of the grant_type parameter contained in the token request from the client application is refresh_token, properties set by this request parameter will be added to the existing extra properties of the corresponding access token. Extra properties having the same keys will be overwritten in the same manner as the case of grant_type=authorization_code.

Otherwise, if the value of the grant_type parameter contained in the token request from the client application is client_credentials, properties set by this request parameter will be used simply as extra properties of a newly created access token. Because Client Credentials flow does not have a preceding authorization request, merging extra properties will not be performed. This is different from the cases of grant_type=authorization_code and grant_type=refresh_token.

In other cases (grant_type=password), properties set by this request parameter will not be used. When you want to associate extra properties with an access token which is issued by Resource Owner Password Credentials flow, use TokenIssueRequest::setProperties() instead.

Keys of extra properties will be used as labels of top-level entries in a JSON response containing an access token which is returned from an authorization server. An example is example_parameter, which you can find in 5.1. Successful Response of 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);

Keys listed below should not be used and they would be ignored on Authlete side even if they were used. It's because they are reserved in RFC 6749 and OpenID Connect Core 1.0.

token_type
expires_in
refresh_token
scope
error
error_description
error_uri
id_token

Note that there is an upper limit on the total size of extra properties. On the server 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, Property> = null: Properties to be associated with the access token.

Return values

TokenRequest —

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

TokenRequest implements ArrayCopyable, Arrayable, Jsonable Uses ArrayTrait, JsonTrait

Interfaces, Classes and Traits

Table of Contents

Methods

copyFromArray()

Parameters

Return values

copyToArray()

Parameters

Return values

fromArray()

Parameters

Return values

fromJson()

Parameters

Return values

getClientCertificate()

Return values

getClientCertificatePath()

Tags

Return values

getClientId()

Return values

getClientSecret()

Return values

getDpop()

Tags

Return values

getHtm()

Tags

Return values

getHtu()

Tags

Return values

getParameters()

Return values

getProperties()

Return values

setClientCertificate()

Parameters

Return values

setClientCertificatePath()

Parameters

Tags

Return values

setClientId()

Parameters

Return values

setClientSecret()

Parameters

Return values

setDpop()

Parameters

Tags

Return values

setHtm()

Parameters

Tags

Return values

setHtu()

Parameters

Tags

Return values

setParameters()

Parameters

Return values

setProperties()

Parameters

Return values

toArray()

Return values

toJson()

Parameters

Return values