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() : string|null
- Create Authorization Code
- exchangeAuthCodeForAccessToken() : array<string|int, mixed>|null
- Exchange Authorization Code for Access Token
- getAccessToken() : array<string|int, mixed>|null
- Get Access Token
- revokeAccessToken() : bool
- Revoke Access Token
Methods
createAuthCode()
Create Authorization Code
public
createAuthCode(array<string|int, mixed> $data) : string|null
This method is called on a valid authorization token request. The $data
array is guaranteed to have the following keys:
-
client_id
: the validatedclient_id
request parameter -
redirect_uri
: the validatedredirect_uri
request parameter -
state
: thestate
request parameter -
code_challenge
: thecode_challenge
request parameter -
code_challenge_method
: thecode_challenge_method
request parameter -
requested_scope
: the value of thescope
request parameter -
me
: the value of theme
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 aprofile
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 ofTaproot\IndieAuth\Callback\AuthorizationFormInterface
. Typically this is thescope
key, which is a valid space-separated scope string listing the scopes granted by the user on the consent screen. Other implementations ofAuthorizationFormInterface
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 string, and return it.
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
string|null —exchangeAuthCodeForAccessToken()
Exchange Authorization Code for Access Token
public
exchangeAuthCodeForAccessToken(string $code, callable $validateAuthCode) : array<string|int, mixed>|null
Attempt to exchange an authorization code identified by $code
for
an access token. Return an array of access token data to be passed onto
the client app 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. It should proceed as follows.
- Attempt to fetch the authorization code data identified by $code. If it does not exist or has expired, return null;
- Pass the authorization code data array to $validateAuthCode for validation.
If there is a problem with the code, a
Taproot\IndieAuth\IndieAuthException
will be thrown. This method should catch it, invalidate the authorization code data, then re-throw the exception for handling by Server. - If the authorization code data passed all checks, convert it into an access token, invalidate the auth code to prevent re-use, and store the access token data internally.
- Return an array of access token data to be passed onto the client app. It MUST
contain the following keys:
-
me
-
access_token
Additonally, it SHOULD contain the following keys: -
scope
, if the token grants any scope And MAY contain additional keys, such as: -
profile
-
expires_at
-
If the authorization code was redeemed at the authorization endpoint, Server will
only pass the me
and profile
keys onto the client. In both cases, it will filter
out code_challenge
keys to prevent that data from accidentally being leaked to
clients. If an access token is present, the server will add token_type: Bearer
automatically.
A typical implementation might look like this:
function exchangeAuthCodeForAccessToken(string $code, callable $validateAuthCode): ?array {
if (is_null($authCodeData = $this->fetchAuthCode($code))) {
return null;
}
if (isExpired($authCodeData)) {
return null;
}
try {
$validateAuthCode($authCodeData);
} catch (IndieAuthException $e) {
$this->deleteAuthCode($code);
throw $e;
}
return $this->newTokenFromAuthCodeData($authCodeData);
}
Refer to reference implementations in the Taproot\IndieAuth\Storage
namespace for
reference.
Parameters
- $code : string
-
The Authorization Code to attempt to exchange.
- $validateAuthCode : callable
-
A callable to perform additional validation if valid auth code data is found. Takes
array $authCodeData
, raisesTaproot\IndieAuth\IndieAuthException
on invalid data, which should be bubbled up to the caller after any clean-up. Returns void.
Return values
array<string|int, mixed>|null —An array of access token data to return to the client on success, null on any error.
getAccessToken()
Get Access Token
public
getAccessToken(string $token) : array<string|int, mixed>|null
Fetch access token data identified by the token $token
, returning
null if it is expired or invalid.
Parameters
- $token : string
Return values
array<string|int, mixed>|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