Documentation

TokenStorageInterface

Token Storage Interface

This interface defines the bare minimum methods required by the Server class in order to implement auth code issuing and exchange flows, as well as to let external code get access tokens (for validating requests authenticated by an access_token) and revoke access tokens.

The contract made between Server and implementations of TokenStorageInterface can broadly be summarized as follows:

  • The Server class is responsible for performing all validation which is defined in the IndieAuth spec and is not implementation-specific. For example: checking validity of all the authorization request parameters, checking that client_id, request_uri and code_verifier parameters in token exchange requests match with the stored data.
  • The TokenStorageInterface class is responsible for performing implementation-specific validation, such as assigning and checking expiry times for auth codes and access tokens.

Implementations of TokenStorageInterface will usually implement additional methods to allow for lower-level querying, saving, updating and deletion of token data. These can be used to, for example, implement a UI for users to review and revoke currently valid access tokens.

The behaviour of TokenStorageInterface is somewhat coupled with the implementation of your authentication handler callback (documented in Server::__construct) and AuthorizationFormInterface, so you should refer to the documentation for both while implementing TokenStorageInterface.

Periodic deletion of expired tokens is out of the scope of this interface. Implementations may choose to offer a clean-up method, and potentially the option to call it once automatically on instantiation.

None of the methods defined on TokenStorageInterface should throw exceptions. Failure, for any reason, is indicated by returning either null or false, depending on the method.

Table of Contents

createAuthCode()  : Token|null
Create Auth Code
exchangeAuthCodeForAccessToken()  : Token|null
Exchange Authorization Code for Access Token
getAccessToken()  : Token|null
Get Access Token
revokeAccessToken()  : bool
Revoke Access Token

Methods

createAuthCode()

Create Auth Code

public createAuthCode(array<string|int, mixed> $data) : Token|null

This method is called on a valid authorization token request. The $data array is guaranteed to have the following keys:

  • client_id: the validated client_id request parameter
  • redirect_uri: the validated redirect_uri request parameter
  • state: the state request parameter
  • code_challenge: the code_challenge request parameter
  • code_challenge_method: the code_challenge_method request parameter
  • requested_scope: the value of the scope request parameter
  • me: the value of the me key from the authentication result returned from the authentication request handler callback

It may also have additional keys, which can come from the following locations:

  • All keys from the the authentication request handler callback result which do not clash with the keys listed above (with the exception of me, which is always present). Usually this is a profile key, but you may choose to return additional data from the authentication callback, which will be present in $data.
  • Any keys added by the transformAuthorizationCode method on the currently active instance of Taproot\IndieAuth\Callback\AuthorizationFormInterface. Typically this is the scope key, which is a valid space-separated scope string listing the scopes granted by the user on the consent screen. Other implementations of AuthorizationFormInterface may add additional data, such as custom token-specific settings, or a custom token lifetime.

This method should store the data passed to it, generate a corresponding authorization code, and return an instance of Storage\Token containing both. Implementations will usually add an expiry time, usually under the valid_until key.

The method call and data is structured such that implementations have a lot of flexibility about how to store authorization code data. It could be a record in an auth code database table, a record in a table which is used for both auth codes and access tokens, or even a stateless self-encrypted token — note that in the latter case, you must persist a copy of the auth code with its exchanged access token to check against, in order to prevent it being exchanged more than once.

On an error, return null. The reason for the error is irrelevant for calling code, but it’s recommended to log it internally for reference. For the same reason, this method should not throw exceptions.

Parameters
$data : array<string|int, mixed>
Return values
Token|null —

exchangeAuthCodeForAccessToken()

Exchange Authorization Code for Access Token

public exchangeAuthCodeForAccessToken(string $code) : Token|null

Attempt to exchange an authorization code identified by $code for an access token, returning it in a Token on success and null on error.

This method is called at the beginning of a code exchange request, before further error checking or validation is applied. On an error, the created access token is immediately revoked via revokeAccessToken().

For this reason, the token data in the returned Token object MUST include the client_id and redirect_uri parameters associated with the authorization code, as these are used by the IndieAuth Server for further validation.

This method is responsible for ensuring that the matched auth code is not expired. If it is, it should return null, presumably after deleting the corresponding authorization code record.

If the exchanged access token should expire, this method should set its expiry time, usually in a valid_until key.

Parameters
$code : string
Return values
Token|null —

getAccessToken()

Get Access Token

public getAccessToken(string $token) : Token|null

Fetch access token data identified by the token $token, returning null if it is expired or invalid. The data should be structured in exactly the same way it was stored by exchangeAuthCodeForAccessToken.

Parameters
$token : string
Return values
Token|null —

revokeAccessToken()

Revoke Access Token

public revokeAccessToken(string $token) : bool

Revoke the access token identified by $token. Return true on success, or false on error, including if the token did not exist.

Parameters
$token : string
Return values
bool —

Search results