Documentation

TokenResponse extends ApiResponse

Response from Authlete's /api/auth/token API.

Authlete's /api/auth/token API returns JSON which can be mapped to this class. The token endpoint implementation should retrieve the value of the action response parameter (which can be obtained by getAction() method of this class) from the response and take the following steps according to the value.

When the value returned from getAction() method is TokenAction::$INVALID_CLIENT, it means that authentication of the client failed. In this case, the HTTP status of the response to the client application should be either 400 Bad Request or 401 Unauthorized. This requirement comes from 5.2. Error Response of RFC 6749. The description about invalid_client shown below is an excerpt from RFC 6749.

Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client.

In either case, the JSON string returned from getResponseContent() method can be used as the entity body of the response to the client application. The following illustrates the response which the token endpoint implementation should generate and return to the client application.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

(The value returned from getResponseContent())

HTTP/1.1 401 Unauthorized
WWW-Authenticate: (challenge)
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

(The value returned from getResponseContent())

When the value returned from getAction() method is TokenAction::$INTERNAL_SERVER_ERROR, it means that the request from your system was wrong or that an error occurred in Authlete. In either case, from a viewpoint of the client application, it is an error on the server side. Therefore, the token endpoint implementation should generate a response to the client application with the HTTP status of 500 Internal Server Error.

In this case, getResponseContent() method returns a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the token endpoint implementation should generate and return to the client application.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

(The value returned from getResponseContent())

When the value returned from getAction() method is TokenAction::$BAD_REQUEST, it means that the request from the client application is invalid. The HTTP status of the response returned to the client application must be 400 Bad Request and the content type must be application/json.

In this case, getResponseContent() method returns a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the token endpoint implementation should generate and return to the client application.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

(The value returned from getResponseContent())

When the value returned from getAction() method is TokenAction::$PASSWORD, it means that the request from the client application is valid and the value of the grant_type request parameter was password. This indicates that the flow is Resource Owner Password Credentials flow.

In this case, getUsername() method returns the value of the username request parameter and getPassword() method returns the value of the password request parameter which were contained in the token request from the client application. The token endpoint implementation must validate the credentials of the resource owner (= end-user) and take either of the actions below according to the validation result.

  1. When the credentials are valid, call Authlete's /api/auth/token/issue API to generate an access. The API requires a ticket request parameter and a subject request parameter. Use the value returned from TokenResponse::getTicket() method as the value for the ticket request parameter.

    The response from /api/auth/token/issue API (TokenIssueResponse) contains data (an access token and others) which should be returned to the client application. Use the data to generate a response to the client application.

  2. When the credentials are invalid, call Authlete's /api/auth/token/fail API with reason=INVALID_RESOURCE_OWNER_CREDENTIALS to generate an error response for the client application. The API requires a ticket request parameter. Use the value returned from TokenResponse::getTicket() method as the value for the ticket request parameter.

    The response from /api/auth/token/fail API (TokenFailResponse) contains error information which should be returned to the client application. Use it to generate a response to the client application.

When the value returned from getAction() method is TokenAction::$OK, it means that the request from the client application is valid, and an access token and optionally an ID token are ready to be issued. The HTTP status of the response returned to the client application must be 200 OK and the content type must be application/json.

In this case, getResponseContent() method returns a JSON string which contains an access token (and optionally an ID token), so it can be used as the entity body of the response. The following illustrates the response which the token endpoint implementation should generate and return to the client application.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

(The value returned from getResponseContent())

Table of Contents

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.
getAccessToken()  : string
Get the newly issued access token.
getAccessTokenDuration()  : int|string
Get the duration of the access token in seconds.
getAccessTokenExpiresAt()  : int|string
Get the date in milliseconds since the Unix epoch (1970-Jan-1) at which the access token will expire.
getAccessTokenResources()  : array<string|int, string>
Get the target resources of the access token.
getAction()  : TokenAction
Get the next action that the token endpoint should take.
getClientId()  : int|string
Get the ID of the client application associated with the access token.
getClientIdAlias()  : string
Get the client ID alias.
getGrantType()  : GrantType
Get the grant type of the token request.
getIdToken()  : string
Get the newly issued ID token.
getJwtAccessToken()  : string
Get the newly issued access token in JWT format.
getPassword()  : string
Get the value of the "password" request parameter contained in the token request from the client application.
getProperties()  : array<string|int, Property>
Get the properties associated with the access token.
getRefreshToken()  : string
Get the newly issued refresh token.
getRefreshTokenDuration()  : int|string
Get the duration of the refresh token in seconds.
getRefreshTokenExpiresAt()  : int|string
Get the date in milliseconds since the Unix epoch (1970-Jan-1) at which the refresh token will expire.
getResources()  : array<string|int, string>
Get the target resources. This represents the resources specified by the `resource` request parameters in the token request.
getResponseContent()  : string
Get the response content which can be used as the entity body of the response returned to the client application.
getResultCode()  : string
Get the code of the result of an Authlete API call.
getResultMessage()  : string
Get the message of the result of an Authlete API call.
getScopes()  : array<string|int, string>
Get the scopes covered by the access token.
getSubject()  : string
Get the subject (= unique identifier) of the end-user (= resource owner) of the access token.
getTicket()  : string
Get the ticket issued from Authlete's /api/auth/token API.
getUsername()  : string
Get the value of the "username" request parameter contained in the token request from the client application.
isClientIdAliasUsed()  : bool
Get the flag which indicates whether the client ID alias was used when the token request was made.
setAccessToken()  : TokenResponse
Set the newly issued access token.
setAccessTokenDuration()  : TokenResponse
Set the duration of the access token in seconds.
setAccessTokenExpiresAt()  : TokenResponse
Set the date in milliseconds since the Unix epoch (1970-Jan-1) at which the access token will expire.
setAccessTokenResources()  : TokenResponse
Set the target resources of the access token.
setAction()  : TokenResponse
Set the next action that the token endpoint should take.
setClientId()  : TokenResponse
Set the ID of the client application associated with the access token.
setClientIdAlias()  : TokenResponse
Set the client ID alias.
setClientIdAliasUsed()  : TokenResponse
Set the flag which indicates whether the client ID alias was used when the token request was made.
setGrantType()  : TokenResponse
Set the grant type of the token request.
setIdToken()  : TokenResponse
Set the newly issued ID token.
setJwtAccessToken()  : TokenResponse
Set the newly issued access token in JWT format.
setPassword()  : TokenResponse
Set the value of the "password" request parameter contained in the token request from the client application.
setProperties()  : TokenResponse
Set the properties associated with the access token.
setRefreshToken()  : TokenResponse
Set the newly issued refresh token.
setRefreshTokenDuration()  : TokenResponse
Set the duration of the refresh token in seconds.
setRefreshTokenExpiresAt()  : TokenResponse
Set the date in milliseconds since the Unix epoch (1970-Jan-1) at which the refresh token will expire.
setResources()  : TokenResponse
Set the target resources. This represents the resources specified by the `resource` request parameters in the token request.
setResponseContent()  : TokenResponse
Set the response content which can be used as the entity body of the response returned to the client application.
setResultCode()  : ApiResponse
Set the code of the result of an Authlete API call.
setResultMessage()  : ApiResponse
Set the message of the result of an Authlete API call.
setScopes()  : TokenResponse
Set the scopes covered by the access token.
setSubject()  : TokenResponse
Set the subject (= unique identifier) of the end-user (= resource owner) of the access token.
setTicket()  : TokenResponse
Set the ticket issued from Authlete's /api/auth/token API.
setUsername()  : TokenResponse
Set the value of the "username" request parameter contained in the token request from the client application.
toArray()  : array<string|int, mixed>
Convert this object into an array.
toJson()  : string
Convert this object into a JSON string.

Methods

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.

getAccessToken()

Get the newly issued access token.

public getAccessToken() : string

This method returns a non-null value only when getAction() method returns TokenAction::$OK.

Return values
string —

The access token.

getAccessTokenDuration()

Get the duration of the access token in seconds.

public getAccessTokenDuration() : int|string
Return values
int|string —

The duration of the access token in seconds.

getAccessTokenExpiresAt()

Get the date in milliseconds since the Unix epoch (1970-Jan-1) at which the access token will expire.

public getAccessTokenExpiresAt() : int|string
Return values
int|string —

The date at which the access token will expire.

getAccessTokenResources()

Get the target resources of the access token.

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

The target resources returned by this method may be the same as or different from the ones returned by getResources() method.

In some flows, the initial request and the subsequent token request are sent to different endpoints. Example flows are the authorization code flow, the refresh token flow, the CIBA ping mode, the CIBA poll mode and the device flow. In these flows, not only the initial request but also the subsequent token request can include the resource request parameters. The purpose of the resource request parameters in the token request is to narrow the range of the target resources from the original set of target resources requested by the preceding initial request. If narrowing down is performed, the target resources returned by getResources() method and the ones returned by this method are different. This method returns the narrowed set of target resources.

Tags
see
https://www.rfc-editor.org/rfc/rfc8707.html

RFC 8707 Resource Indicators for OAuth 2.0

since
1.8
Return values
array<string|int, string> —

The target resources of the access token.

getAction()

Get the next action that the token endpoint should take.

public getAction() : TokenAction
Return values
TokenAction —

The next action that the token endpoint should take.

getClientId()

Get the ID of the client application associated with the access token.

public getClientId() : int|string
Return values
int|string —

The client ID.

getClientIdAlias()

Get the client ID alias.

public getClientIdAlias() : string

If no alias is assigned to the client application, this method returns null.

Return values
string —

The client ID alias.

getGrantType()

Get the grant type of the token request.

public getGrantType() : GrantType
Return values
GrantType —

The grant type of the token request.

getIdToken()

Get the newly issued ID token.

public getIdToken() : string

An ID token is issued from a token endpoint when the authorization code follow is used and openid is included in the scope list.

Return values
string —

The newly issued ID token.

getJwtAccessToken()

Get the newly issued access token in JWT format.

public getJwtAccessToken() : string

If the authorization server is configured to issue JWT-based access tokens (= if Service.getAccessTokenSignAlg() returns a non-null value), a JWT-based access token is issued along with the original random-string one.

Tags
since
1.8
Return values
string —

The newly issued access token in JWT format.

getPassword()

Get the value of the "password" request parameter contained in the token request from the client application.

public getPassword() : string
Return values
string —

The value of the password request parameter.

getProperties()

Get the properties associated with the access token.

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

The properties associated with the access token.

getRefreshToken()

Get the newly issued refresh token.

public getRefreshToken() : string

This method returns a non-null value only when getAction() method returns TokenAction::$OK and the service is configured to support the refresh token flow.

Return values
string —

The newly issued access token.

getRefreshTokenDuration()

Get the duration of the refresh token in seconds.

public getRefreshTokenDuration() : int|string
Return values
int|string —

The duration of the refresh token in seconds.

getRefreshTokenExpiresAt()

Get the date in milliseconds since the Unix epoch (1970-Jan-1) at which the refresh token will expire.

public getRefreshTokenExpiresAt() : int|string
Return values
int|string —

The date at which the refresh token will expire.

getResources()

Get the target resources. This represents the resources specified by the `resource` request parameters in the token request.

public getResources() : array<string|int, string>
Tags
see
https://www.rfc-editor.org/rfc/rfc8707.html

RFC 8707 Resource Indicators for OAuth 2.0

since
1.8
Return values
array<string|int, string> —

The target resources.

getResponseContent()

Get the response content which can be used as the entity body of the response returned to the client application.

public getResponseContent() : string
Return values
string —

The response content.

getResultCode()

Get the code of the result of an Authlete API call.

public getResultCode() : string
Return values
string —

The result code.

getResultMessage()

Get the message of the result of an Authlete API call.

public getResultMessage() : string
Return values
string —

The result message.

getScopes()

Get the scopes covered by the access token.

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

The scopes covered by the access token.

getSubject()

Get the subject (= unique identifier) of the end-user (= resource owner) of the access token.

public getSubject() : string

Even if an access token was issued by the call of /api/auth/token API, this method returns null if the flow of the token request was Client Credentials flow (grant_type=client_credentials) because access tokens are not associated with any specific end-user in the flow.

Return values
string —

The subject of the end-user (= resource owner) of the access token.

getTicket()

Get the ticket issued from Authlete's /api/auth/token API.

public getTicket() : string

The value is to be used as the value of the ticket rquest parameter when you call /api/auth/token/issue API or /api/auth/token/fail API.

Return values
string —

The ticket issued from Authlete's /api/auth/token API.

getUsername()

Get the value of the "username" request parameter contained in the token request from the client application.

public getUsername() : string
Return values
string —

The value of the username request parameter.

isClientIdAliasUsed()

Get the flag which indicates whether the client ID alias was used when the token request was made.

public isClientIdAliasUsed() : bool
Return values
bool —

true if the client ID alias was used by the token request.

setAccessToken()

Set the newly issued access token.

public setAccessToken(string $accessToken) : TokenResponse
Parameters
$accessToken : string

The access token.

Return values
TokenResponse —

$this object.

setAccessTokenDuration()

Set the duration of the access token in seconds.

public setAccessTokenDuration(int|string $duration) : TokenResponse
Parameters
$duration : int|string

The duration of the access token in seconds.

Return values
TokenResponse —

$this object.

setAccessTokenExpiresAt()

Set the date in milliseconds since the Unix epoch (1970-Jan-1) at which the access token will expire.

public setAccessTokenExpiresAt(int|string $expiresAt) : TokenResponse
Parameters
$expiresAt : int|string

The date at which the access token will expire.

Return values
TokenResponse —

$this object.

setAccessTokenResources()

Set the target resources of the access token.

public setAccessTokenResources([array<string|int, string> $resources = null ]) : TokenResponse

See the description of getAccessTokenResources() method for details about the target resources of the access token.

Parameters
$resources : array<string|int, string> = null

The target resources of the access token.

Tags
see
https://www.rfc-editor.org/rfc/rfc8707.html

RFC 8707 Resource Indicators for OAuth 2.0

since
1.8
Return values
TokenResponse —

$this object.

setClientId()

Set the ID of the client application associated with the access token.

public setClientId(int|string $clientId) : TokenResponse
Parameters
$clientId : int|string

The client ID.

Return values
TokenResponse —

$this object.

setClientIdAlias()

Set the client ID alias.

public setClientIdAlias(string $alias) : TokenResponse
Parameters
$alias : string

The client ID alias.

Return values
TokenResponse —

$this object.

setClientIdAliasUsed()

Set the flag which indicates whether the client ID alias was used when the token request was made.

public setClientIdAliasUsed(bool $used) : TokenResponse
Parameters
$used : bool

true to indicate that the client ID alias was used by the token request.

Return values
TokenResponse —

$this object.

setIdToken()

Set the newly issued ID token.

public setIdToken(string $idToken) : TokenResponse
Parameters
$idToken : string

The newly issued ID token.

Return values
TokenResponse —

$this object.

setJwtAccessToken()

Set the newly issued access token in JWT format.

public setJwtAccessToken(string $jwtAccessToken) : TokenResponse
Parameters
$jwtAccessToken : string

The newly issued access token in JWT format.

Tags
since
1.8
Return values
TokenResponse —

$this object.

setPassword()

Set the value of the "password" request parameter contained in the token request from the client application.

public setPassword(string $password) : TokenResponse
Parameters
$password : string

The value of the password request parameter.

Return values
TokenResponse —

$this object.

setProperties()

Set the properties associated with the access token.

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

The properties associated with the access token.

Return values
TokenResponse —

$this object.

setRefreshToken()

Set the newly issued refresh token.

public setRefreshToken(string $refreshToken) : TokenResponse
Parameters
$refreshToken : string

The newly issued access token.

Return values
TokenResponse —

$this object.

setRefreshTokenDuration()

Set the duration of the refresh token in seconds.

public setRefreshTokenDuration(int|string $duration) : TokenResponse
Parameters
$duration : int|string

The duration of the refresh token in seconds.

Return values
TokenResponse —

$this object.

setRefreshTokenExpiresAt()

Set the date in milliseconds since the Unix epoch (1970-Jan-1) at which the refresh token will expire.

public setRefreshTokenExpiresAt(int|string $expiresAt) : TokenResponse
Parameters
$expiresAt : int|string

The date at which the refresh token will expire.

Return values
TokenResponse —

$this object.

setResources()

Set the target resources. This represents the resources specified by the `resource` request parameters in the token request.

public setResources([array<string|int, string> $resources = null ]) : TokenResponse
Parameters
$resources : array<string|int, string> = null

The target resources.

Tags
see
https://www.rfc-editor.org/rfc/rfc8707.html

RFC 8707 Resource Indicators for OAuth 2.0

since
1.8
Return values
TokenResponse —

$this object.

setResponseContent()

Set the response content which can be used as the entity body of the response returned to the client application.

public setResponseContent(string $responseContent) : TokenResponse
Parameters
$responseContent : string

The response content.

Return values
TokenResponse —

$this object.

setResultCode()

Set the code of the result of an Authlete API call.

public setResultCode(string $resultCode) : ApiResponse
Parameters
$resultCode : string

The result code.

Return values
ApiResponse —

$this object.

setResultMessage()

Set the message of the result of an Authlete API call.

public setResultMessage(string $resultMessage) : ApiResponse
Parameters
$resultMessage : string

The result message.

Return values
ApiResponse —

$this object.

setScopes()

Set the scopes covered by the access token.

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

The scopes covered by the access token.

Return values
TokenResponse —

$this object.

setSubject()

Set the subject (= unique identifier) of the end-user (= resource owner) of the access token.

public setSubject(string $subject) : TokenResponse
Parameters
$subject : string

The subject of the end-user (= resource owner) of the access token.

Return values
TokenResponse —

$this object.

setTicket()

Set the ticket issued from Authlete's /api/auth/token API.

public setTicket(string $ticket) : TokenResponse
Parameters
$ticket : string

The ticket issued from Authlete's /api/auth/token API.

Return values
TokenResponse —

$this object.

setUsername()

Set the value of the "username" request parameter contained in the token request from the client application.

public setUsername(string $username) : TokenResponse
Parameters
$username : string

The value of the username request parameter.

Return values
TokenResponse —

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

Search results