Documentation

AccessTokenValidator
in package

Access token validator.

// An implementation of the AuthleteApi interface.
$api = ...;

// Create an access token validator.
$validator = new AccessTokenValidator($api);

// Extract an access token from the request.
$accessToken = WebUtility::extractAccessToken($request);

// Set the access token that should be validated.
$validator->setAccessToken($accessToken);

// [Optional]
// Set scopes required to access the protected resource endpoint.
$requiredScopes = array(...);
$validator->setRequiredScopes($requiredScopes);

// [Optional]
// Set a subject (unique user identifier) that must be associated
// with the access token.
$requiredSubject = ...;
$validator->setRequiredSubject($requiredSubject);

// [Optional]
// Set the client certificate that the client application presented.
$clientCertificate = ...;
$validator->setClientCertificate($clientCertificate);

// Perform validation. This triggers an API call to Authlete's
// /api/auth/introspection API.
$valid = $validator->validate();

// If the access token is not valid.
if ($valid === false)
{
    // If the call to /api/auth/introspection API made by the
    // implementation of validate() method threw an exception,
    // `getIntrospectionException()` method returns the exception.
    $introspectionException = $validator->getIntrospectionException();

    // If the call to /api/auth/introspection API made by the
    // implementation of validate() method succeeded,
    // `getIntrospectionResponse()` method returns the response
    // from the API (an instance of IntrospectionResponse).
    $introspectionResponse = $validator->getIntrospectionResponse();

    // When validate() method returns false, `getErrorResponse()`
    // returns an error response (an instance of Response) that
    // complies with RFC 6750.
    $response = $validator->getErrorResponse();

    // Return the error response to the client application.
    return $response;
}

// The access token is valid. The instance returned from
// `getIntrospectionResponse()` holds information about the access token.
$info = $validator->getIntrospectionResponse();

// For example, the ID of the client application to which the access has
// been issued.
$clientId = $info->getClientId();

create() method is a shortcut method to create a validator.

// Create a validator. The access token is extracted from
// the Authorization header of the request.
$validator = AccessTokenValidator::create(
    $api, $request, $requiredScopes, $requiredSubject);

// Validate the access token.
if ($validator->validate() === false)
{
    // Return an error response that complies with RFC 6750.
    return $validator->getErrorResponse();
}

Table of Contents

Methods

__construct()  : mixed
Constructor.
create()  : AccessTokenValidator
Create a validator.
getAccessToken()  : string
Get the access token which was presented by the client application.
getClientCertificate()  : string
Get the client certificate which the client application presented at the protected resource endpoint.
getErrorResponse()  : Response
Get the error response that the protected resource endpoint should return to the client application.
getIntrospectionException()  : Exception
Get the exception which was raised during the call to Authlete's /api/auth/introspection API.
getIntrospectionResponse()  : IntrospectionResponse
Get the response from Authlete's /api/auth/introspection API.
getRequiredScopes()  : array<string|int, string>
Get the scopes which are required to access the protected resource endpoint.
getRequiredSubject()  : string
Get the subject (= the unique identifier of a user) which is required to be associated with the access token.
isValid()  : bool
Get the result of the access token validation.
setAccessToken()  : AccessTokenValidator
Set the access token which was presented by the client application.
setClientCertificate()  : AccessTokenValidator
Set the client certificate which the client application presented at the protected resource endpoint.
setRequiredScopes()  : AccessTokenValidator
Set the scopes which are required to access the protected resource endpoint.
setRequiredSubject()  : AccessTokenValidator
Set the subject (= the unique identifier of a user) which is required to be associated with the access token.
validate()  : bool
Validate the access token.

Methods

__construct()

Constructor.

public __construct(AutheteApi $api) : mixed
Parameters
$api : AutheteApi

An implementation of the AuthleteApi interface.

create()

Create a validator.

public static create(AuthleteApi $api, Request $request[, array<string|int, string> $requiredScopes = null ][, string $requiredSubject = null ]) : AccessTokenValidator

The access token is extracted from the Authorization header of the request. Note that the access_token query parameter and the access_token form parameter are NOT referred to even if they exist.

Parameters
$api : AuthleteApi

An implementation of the AuthleteApi interface.

$request : Request

A request from a client application.

$requiredScopes : array<string|int, string> = null

Scopes which are required to access the protected resource endpoint. This argument is optional and its default value is null.

$requiredSubject : string = null

Subject (= unique user identifier) which is required to be associated with the access token. This argument is optional and its default value is null.

Return values
AccessTokenValidator —

A new AccessTokenValidator instance.

getAccessToken()

Get the access token which was presented by the client application.

public getAccessToken() : string
Return values
string —

The access token.

getClientCertificate()

Get the client certificate which the client application presented at the protected resource endpoint.

public getClientCertificate() : string
Return values
string —

The client certificate in PEM format.

getErrorResponse()

Get the error response that the protected resource endpoint should return to the client application.

public getErrorResponse() : Response

If the result of validate() is false, an error response is generated and set to this property.

Note that this property remains null if the result of validate() is true.

On entry of validate() method, this property is reset to null.

Return values
Response —

An error response that complies with RFC 6750 (The OAuth 2.0 Authorization Framework: Bearer Token Usage).

getIntrospectionException()

Get the exception which was raised during the call to Authlete's /api/auth/introspection API.

public getIntrospectionException() : Exception

validate() method internally calls Authlete's /api/auth/introspection API. If the API call threw an exception, the exception is set to this property.

Note that this property remains null if the API call succeeded. In the successful case, getIntrospectionResponse() returns a non-null value.

On entry of validate() method, this property is reset to null.

Return values
Exception —

The exception raised during the call to Authlete's /api/auth/authorization API.

getIntrospectionResponse()

Get the response from Authlete's /api/auth/introspection API.

public getIntrospectionResponse() : IntrospectionResponse

validate() method internally calls /api/auth/introspection API. This method returns the response from the API call.

Note that this property remains null if the API call threw an exception. In the error case, getIntrospectionException() returns a non-null value.

On entry of validate() method, this property is reset to null.

Return values
IntrospectionResponse —

The response from Authlete's /api/auth/introspection API.

getRequiredScopes()

Get the scopes which are required to access the protected resource endpoint.

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

The required scopes. This method always returns an array and never returns null.

getRequiredSubject()

Get the subject (= the unique identifier of a user) which is required to be associated with the access token.

public getRequiredSubject() : string
Return values
string —

The required subject.

isValid()

Get the result of the access token validation.

public isValid() : bool

After the call to validate() method, this method returns the same value which was returned by validate().

On entry of validate() method, this property is reset to false.

Return values
bool —

true if the access token is valid (= has the right to access the protected resource endpoint).

setClientCertificate()

Set the client certificate which the client application presented at the protected resource endpoint.

public setClientCertificate(string $clientCertificate) : AccessTokenValidator
Parameters
$clientCertificate : string

The client certificate in PEM format.

Return values
AccessTokenValidator —

$this object.

setRequiredScopes()

Set the scopes which are required to access the protected resource endpoint.

public setRequiredScopes([array<string|int, string> $requiredScopes = null ]) : AccessTokenValidator
Parameters
$requiredScopes : array<string|int, string> = null

The required scopes.

Return values
AccessTokenValidator —

$this object.

setRequiredSubject()

Set the subject (= the unique identifier of a user) which is required to be associated with the access token.

public setRequiredSubject(string $requiredSubject) : AccessTokenValidator
Parameters
$requiredSubject : string

The required subject.

Return values
AccessTokenValidator —

$this object.

validate()

Validate the access token.

public validate() : bool

On entry, as the first step, the implementation of this method resets the following properties to false or null.

  • valid
  • introspectionResponse
  • introspectionException
  • errorResponse

Then, this method internally calls Authlete's /api/auth/introspection API to get information about the access token.

If the API call failed, the exception thrown by the API call is set to the introspectionException property, an error response (500 Internal Server Error) is set to the errorResponse property, and false is set to the valid property. Then, this method returns false.

If the API call succeeded, the response from the API is set to the introspectionResponse property. Then, the implementation of this method checks the value of the action parameter in the response from the API.

If the value of the action parameter is OK, this method sets true to the valid property and returns true.

If the value of the action parameter is not OK, this method builds an error response that should be returned to the client application and sets it to the errorResponse property. Then, this method sets false to the valid property and returns false.

This method returns true if the access token is valid. "Valid" here means that the access token exists, has not expired, covers all the required scopes (if required scopes have been set by setRequiredScopes() method), and is associated with the required subject (if a required subject has been set by setRequiredSubject() method).

In addition, if the access token is bound to a client certificate (see "OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access" for details), it is checked whether the client certificate (set by setClientCertificate() method) is identical to the bound certificate.

Return values
bool —

true if the access token is valid (= has the right to access the protected resource endpoint).


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results