Documentation

IntrospectionResponse extends ApiResponse

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

Authlete's /api/auth/introspection API returns JSON which can be mapped to this class. The resource server should retrieve the value of the action response parameter from the response and take the following steps according to the value.

When the value returned from getAction() method is IntrospectionAction::$INTERNAL_SERVER_ERROR, it means that the request from the resource server 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 resource server should generate a response to the client application with the HTTP status of 500 Internal Server Error.

In this case, getResponseContent() method returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the resource server wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from getResponseContent() method can be used as the value of the WWW-Authenticate header. The following is an example response which complies with RFC 6750.

HTTP/1.1 500 Internal Server Error
WWW-Authenticate: (The value returned from getResponseContent())
Cache-Control: no-store
Pragma: no-cache

When the value returned from getAction() method is IntrospectionAction::$BAD_REQUEST, it means that the request from the client application does not contain an access token (= the request from the resource server to Authlete does not contain the token request parameter).

In this case, getResponseContent() method returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the resource server wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from getResponseContent() method can be used as the value of the WWW-Authenticate header. The following is an example response which complies with RFC 6750.

HTTP/1.1 400 Bad Request
WWW-Authenticate: (The value returned from getResponseContent())
Cache-Control: no-store
Pragma: no-cache

When the value returned from getAction() method is IntrospectionAction::$UNAUTHORIZED, it means that the access token does not exist or has expired. Or the client application associated with the access token does not exist any longer.

In this case, getResponseContent() method returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the resource server wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from getResponseContent() method can be used as the value of the WWW-Authenticate header. The following is an example response which complies with RFC 6750.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: (The value returned from getResponseContent())
Cache-Control: no-store
Pragma: no-cache

When the value returned from getAction() method is IntrospectionAction::$FORBIDDEN, it means that the access token does not cover the required scopes or that the subject associated with the access token is different from the subject specified by the API call.

In this case, getResponseContent() method returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the resource server wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from getResponseContent() method can be used as the value of the WWW-Authenticate header. The following is an example response which complies with RFC 6750.

HTTP/1.1 403 Forbidden
WWW-Authenticate: (The value returned from getResponseContent())
Cache-Control: no-store
Pragma: no-cache

When the value returned from getAction() method is IntrospectionAction::$OK, it means that the access token which the client application presented is valid (= exists and has not expired). The resource server is supposed to return the proteced resource to the client application.

In this case, getResponseContent() property returns Bearer error=\"invalid_request\"". This is the simplest string which can be used as the value of the WWW-Authenticate header to indicate 400 Bad Request. The resource server may use this string to tell the client application that the request was bad. But in such a case, if possible, the resource server should generate a more informative error message to help developers of client applications. The following is an example error response which complies with RFC 6750.

HTTP/1.1 400 Bad Request
WWW-Authenticate: (The value returned from getResponseContent())
Cache-Control: no-store
Pragma: no-cache

Basically, getResponseContent() method returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the resource server has selected Bearer as the token type, the string returned from getResponseContent() method can be used directly as the value for the WWW-Authenticate header. However, if the service has selected another different token type, the resource server has to generate error message for itself.

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.
getAccessTokenResources()  : array<string|int, string>
Get the target resources of the access token.
getAction()  : IntrospectionAction
Get the next action that the resource server should take.
getCertificateThumbprint()  : string
Get the client certificate thumbprint used to validate the access token.
getClientAttributes()  : array<string|int, Pair>
Get the attributes of the client that the access token has been issued to.
getClientId()  : int|string
Get the client ID of the client application to which the access token has been issued.
getClientIdAlias()  : string
Get the client ID alias when the authorization request or the token request for the access token was made.
getConsentedClaims()  : array<string|int, string>
Get the claims that the user has consented for the client application to know.
getExpiresAt()  : int|string
Get the time at which the access token will expire.
getGrantId()  : string
Get the grant ID which the access token is tied to.
getProperties()  : array<string|int, Property>
Get the properties associated with the access token.
getResources()  : array<string|int, string>
Get the target resources. This represents the resources specified by the `resource` request parameters or by the `resource` property in the request object.
getResponseContent()  : string
Get the response content which can be used as a part of the response 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.
getScopeDetails()  : array<string|int, Scope>
Get the details of the scopes.
getScopes()  : array<string|int, string>
Get the scopes that are associated with the access token.
getServiceAttributes()  : array<string|int, Pair>
Get the attributes of the service that the client application belongs to.
getSubject()  : string
Get the subject (= unique identifier) of the end-user (= resource owner) who allowed the authorization server to issue the access token to the client application.
isActive()  : bool
Get the flag which indicates whether the access token is active (= exists and has not expired).
isClientIdAliasUsed()  : bool
Get the flag which indicates whether the client ID alias was used when the authorization request or the token request for the access token was made.
isExistent()  : bool
Get the flag which indicates whether the access token exists or not.
isForExternalAttachment()  : bool
Get the flag which indicates whether the access token is for an external attachment.
isRefreshable()  : bool
Get the flag which indicates whether the access token can be refreshed using the associated refresh token.
isSufficient()  : bool
Get the flag which indicates whether the access token covers the required scopes.
isUsable()  : bool
Get the flag which indicates whether the access token is usable (= exists and has not expired).
setAccessTokenResources()  : IntrospectionResponse
Set the target resources of the access token.
setAction()  : IntrospectionAction
Set the next action that the resource server should take.
setActive()  : IntrospectionResponse
Set the flag which indicates whether the access token is active (= exists and has not expired).
setCertificateThumbprint()  : IntrospectionResponse
Set the client certificate thumbprint used to validate the access token.
setClientAttributes()  : IntrospectionResponse
Set the attributes of the client that the access token has been issued to.
setClientId()  : IntrospectionAction
Set the client ID of the client application to which the access token has been issued.
setClientIdAlias()  : IntrospectionResponse
Set the client ID alias when the authorization request or the token request for the access token was made.
setClientIdAliasUsed()  : IntrospectionResponse
Set the flag which indicates whether the client ID alias was used when the authorization request or the token request for the access token was made.
setConsentedClaims()  : IntrospectionResponse
Set the claims that the user has consented for the client application to know.
setExistent()  : IntrospectionResponse
Set the flag which indicates whether the access token exists or not.
setExpiresAt()  : mixed
Set the time at which the access token will expire.
setForExternalAttachment()  : IntrospectionResponse
Set the flag which indicates whether the access token is for an external attachment.
setGrantId()  : IntrospectionAction
Set the grant ID which the access token is tied to.
setProperties()  : IntrospectionResponse
Set the properties associated with the access token.
setRefreshable()  : IntrospectionResponse
Set the flag which indicates whether the access token can be refreshed using the associated refresh token.
setResources()  : IntrospectionResponse
Set the target resources. This represents the resources specified by the `resource` request parameters or by the `resource` property in the request object.
setResponseContent()  : IntrospectionResponse
Set the response content which can be used as a part of the response 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.
setScopeDetails()  : IntrospectionResponse
Set the details of the scopes.
setScopes()  : IntrospectionResponse
Set the scopes that are associated with the access token.
setServiceAttributes()  : IntrospectionResponse
Set the attributes of the service that the client application belongs to.
setSubject()  : IntrospectionAction
Set the subject (= unique identifier) of the end-user (= resource owner) who allowed the authorization server to issue the access token to the client application.
setSufficient()  : IntrospectionResponse
Set the flag which indicates whether the access token covers the required scopes.
setUsable()  : IntrospectionResponse
Set the flag which indicates whether the access token is usable (= exists and has not expired).
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.

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.

getCertificateThumbprint()

Get the client certificate thumbprint used to validate the access token.

public getCertificateThumbprint() : string
Tags
since
1.3
Return values
string —

The certificate thumbprint, calculated as the SHA-256 hash of the DER-encoded certificate value.

getClientAttributes()

Get the attributes of the client that the access token has been issued to.

public getClientAttributes() : array<string|int, Pair>
Tags
since
1.11
Return values
array<string|int, Pair> —

The attributes of the client.

getClientId()

Get the client ID of the client application to which the access token has been issued.

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

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

getClientIdAlias()

Get the client ID alias when the authorization request or the token request for the access token was made.

public getClientIdAlias() : string

Note that this value may be different from the current client ID alias.

Tags
since
1.3
Return values
string —

The client ID alias when the authorization request or the token request for the access token was made.

getConsentedClaims()

Get the claims that the user has consented for the client application to know.

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

Some Authlete APIs accept a consentedClaims request parameter (which is available from Authlete 2.3). This consentedClaims property holds the value specified by the request parameter.

Tags
since
1.11
Return values
array<string|int, string> —

The consented claims.

getExpiresAt()

Get the time at which the access token will expire.

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

The time at which the access token will expire. The value is represented as milliseconds since the Unix epoch (1970-Jan-1).

getGrantId()

Get the grant ID which the access token is tied to.

public getGrantId() : string

In Authlete, when an authorization request includes the grant_management_action request parameter, a grant ID (which may be a newly-generated one or an existing one specified by the grant_id request parameter) is tied to the access token which is created as a result of the authorization request.

Tags
since
1.11
Return values
string —

The grant ID tied to the access token.

getProperties()

Get the properties associated with the access token.

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

Properties.

getResources()

Get the target resources. This represents the resources specified by the `resource` request parameters or by the `resource` property in the request object.

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 a part of the response 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.

getScopeDetails()

Get the details of the scopes.

public getScopeDetails() : array<string|int, Scope>

The scopes property of this class is a list of scope names. The property does not hold information about scope attributes. This scopeDetails property was newly created to convey information about scope attributes.

Tags
since
1.11
Return values
array<string|int, Scope> —

The details of the scopes.

getScopes()

Get the scopes that are associated with the access token.

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

The scopes associated with the access token.

getServiceAttributes()

Get the attributes of the service that the client application belongs to.

public getServiceAttributes() : array<string|int, Pair>
Tags
since
1.11
Return values
array<string|int, Pair> —

The attributes of the service.

getSubject()

Get the subject (= unique identifier) of the end-user (= resource owner) who allowed the authorization server to issue the access token to the client application.

public getSubject() : string
Return values
string —

The subject of the end-user associated with the access token.

isActive()

Get the flag which indicates whether the access token is active (= exists and has not expired).

public isActive() : bool

This method is just an alias of isUsable() method. The reason this method was added is to mitigate confusion that those who are familiar with RFC 7662 (OAuth 2.0 Token Introspection) may have.

Return values
bool —

true if the access token is active (= exists and has not expired).

isClientIdAliasUsed()

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

public isClientIdAliasUsed() : bool
Tags
since
1.3
Return values
bool —

true if the client ID alias was used when the authorization request or the token request for the access token was made.

isExistent()

Get the flag which indicates whether the access token exists or not.

public isExistent() : bool
Return values
bool —

true if the access token exists.

isForExternalAttachment()

Get the flag which indicates whether the access token is for an external attachment.

public isForExternalAttachment() : bool

OpenID Provider implementations can make Authlete generate access tokens for external attachments and embed them in ID tokens and userinfo responses by setting true to the accessTokenForExternalAttachmentEmbedded property of the service. If the token presented at Authlete's /auth/introspection API has been generated by the feature, this forExternalAttachment property in the response from the Authlete API becomes true.

Tags
since
1.11
Return values
bool —

true if the access token is for an external attachment.

isRefreshable()

Get the flag which indicates whether the access token can be refreshed using the associated refresh token.

public isRefreshable() : bool

Even if there exists a refresh token associated with the access token, this property returns false if the refresh token has already expired.

Return values
bool —

true if the access token can be refreshed using the associated refresh token.

isSufficient()

Get the flag which indicates whether the access token covers the required scopes.

public isSufficient() : bool
Return values
bool —

true if the access token covers the required scopes.

isUsable()

Get the flag which indicates whether the access token is usable (= exists and has not expired).

public isUsable() : bool
Return values
bool —

true if the access token is usable (= exists and has not expired).

setAccessTokenResources()

Set the target resources of the access token.

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

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
IntrospectionResponse —

$this object.

setActive()

Set the flag which indicates whether the access token is active (= exists and has not expired).

public setActive(bool $active) : IntrospectionResponse

This method is just an alias of setUsable($usable) method. The reason this method was added is to mitigate confusion that those who are familiar with RFC 7662 (OAuth 2.0 Token Introspection) may have.

Parameters
$active : bool

true if the access token is active (= exists and has not expired).

Return values
IntrospectionResponse —

$this object.

setCertificateThumbprint()

Set the client certificate thumbprint used to validate the access token.

public setCertificateThumbprint(string $thumbprint) : IntrospectionResponse
Parameters
$thumbprint : string

The certificate thumbprint, calculated as the SHA-256 hash of the DER-encoded certificate value.

Tags
since
1.3
Return values
IntrospectionResponse —

$this object.

setClientAttributes()

Set the attributes of the client that the access token has been issued to.

public setClientAttributes([array<string|int, Pair> $attributes = null ]) : IntrospectionResponse
Parameters
$attributes : array<string|int, Pair> = null

The attributes of the client.

Tags
since
1.11
Return values
IntrospectionResponse —

$this object.

setClientId()

Set the client ID of the client application to which the access token has been issued.

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

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

Return values
IntrospectionAction —

$this object.

setClientIdAlias()

Set the client ID alias when the authorization request or the token request for the access token was made.

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

The client ID alias.

Tags
since
1.3
Return values
IntrospectionResponse —

$this object.

setClientIdAliasUsed()

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

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

true if the client ID alias was used when the authorization request or the token request for the access token was made.

Tags
since
1.3
Return values
IntrospectionResponse —

$this object.

setConsentedClaims()

Set the claims that the user has consented for the client application to know.

public setConsentedClaims([array<string|int, string> $claims = null ]) : IntrospectionResponse

Some Authlete APIs accept a consentedClaims request parameter (which is available from Authlete 2.3). This consentedClaims property holds the value specified by the request parameter.

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

The consented claims.

Tags
since
1.11
Return values
IntrospectionResponse —

$this object.

setExpiresAt()

Set the time at which the access token will expire.

public setExpiresAt(int|string $expiresAt) : mixed
Parameters
$expiresAt : int|string

The time at which the access token will expire. The value should be represented as milliseconds since the Unix epoch (1970-Jan-1).

Return values
mixed —

setForExternalAttachment()

Set the flag which indicates whether the access token is for an external attachment.

public setForExternalAttachment(bool $forExternalAttachment) : IntrospectionResponse

OpenID Provider implementations can make Authlete generate access tokens for external attachments and embed them in ID tokens and userinfo responses by setting true to the accessTokenForExternalAttachmentEmbedded property of the service. If the token presented at Authlete's /auth/introspection API has been generated by the feature, this forExternalAttachment property in the response from the Authlete API becomes true.

Parameters
$forExternalAttachment : bool

true to indicate that the access token is for an external attachment.

Tags
since
1.11
Return values
IntrospectionResponse —

$this object.

setGrantId()

Set the grant ID which the access token is tied to.

public setGrantId(string $grantId) : IntrospectionAction

In Authlete, when an authorization request includes the grant_management_action request parameter, a grant ID (which may be a newly-generated one or an existing one specified by the grant_id request parameter) is tied to the access token which is created as a result of the authorization request.

Parameters
$grantId : string

The grant ID tied to the access token.

Tags
since
1.11
Return values
IntrospectionAction —

$this object.

setRefreshable()

Set the flag which indicates whether the access token can be refreshed using the associated refresh token.

public setRefreshable(bool $refreshable) : IntrospectionResponse
Parameters
$refreshable : bool

true if the access token can be refreshed using the associated refresh token.

Return values
IntrospectionResponse —

$this object.

setResources()

Set the target resources. This represents the resources specified by the `resource` request parameters or by the `resource` property in the request object.

public setResources([array<string|int, string> $resources = null ]) : IntrospectionResponse
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
IntrospectionResponse —

$this object.

setResponseContent()

Set the response content which can be used as a part of the response to the client application.

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

The response content.

Return values
IntrospectionResponse —

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

setScopeDetails()

Set the details of the scopes.

public setScopeDetails([array<string|int, Scope> $scopeDetails = null ]) : IntrospectionResponse

The scopes property of this class is a list of scope names. The property does not hold information about scope attributes. This scopeDetails property was newly created to convey information about scope attributes.

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

The details of the scopes.

Tags
since
1.11
Return values
IntrospectionResponse —

$this object.

setScopes()

Set the scopes that are associated with the access token.

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

The scopes associated with the access token.

Return values
IntrospectionResponse —

$this object.

setServiceAttributes()

Set the attributes of the service that the client application belongs to.

public setServiceAttributes([array<string|int, Pair> $attributes = null ]) : IntrospectionResponse
Parameters
$attributes : array<string|int, Pair> = null

The attributes of the service.

Tags
since
1.11
Return values
IntrospectionResponse —

$this object.

setSubject()

Set the subject (= unique identifier) of the end-user (= resource owner) who allowed the authorization server to issue the access token to the client application.

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

The subject of the end-user associated with the access token.

Return values
IntrospectionAction —

$this object.

setUsable()

Set the flag which indicates whether the access token is usable (= exists and has not expired).

public setUsable(bool $usable) : IntrospectionResponse
Parameters
$usable : bool

true if the access token is usable (= exists and has not expired).

Return values
IntrospectionResponse —

$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