Documentation

DefaultAuthorizationForm
in package
implements AuthorizationFormInterface, LoggerAwareInterface

Default Authorization Form

This implementation of AuthorizationFormInterface is used by Server if the user doesn’t provide one of their own. It presents the user with a simple consent screen, showing any available details about the client app, and allowing the user to grant any requested scopes.

When the form is submitted, any granted scopes are then added to the authorization code data.

You can customise the authorization template used by passing either path to your own template or a custom callable to the constructor. Refer to the default template /templates/default_authorization_page.html.php as a starting point.

If you want to add additional form controls (e.g. configurable token lifetimes), as well as making a new template, you’ll need to make a subclass which overrides DefaultAuthorizationForm::transformAuthorizationCode() to additionally handle your new form data.

For any more involved customisation, it may make sense to create your own implementation of AuthorizationFormInterface.

Interfaces, Classes, Traits and Enums

AuthorizationFormInterface
Authorization Form Interface
LoggerAwareInterface

Table of Contents

$csrfKey  : string
$formTemplateCallable  : callable
$logger  : LoggerInterface
__construct()  : mixed
Constructor
setLogger()  : void
showForm()  : ResponseInterface
Show Form
transformAuthorizationCode()  : array<string|int, mixed>
Transform Authorization Code

Properties

Methods

__construct()

Constructor

public __construct([string|callable|null $formTemplate = null ][, string|null $csrfKey = null ][, LoggerInterface|null $logger = null ]) : mixed
Parameters
$formTemplate : string|callable|null = null

The path to a custom template, or a template callable with the signature function (array $context): string. Uses the default if null.

$csrfKey : string|null = null

The key used to retrieve a CSRF token from the request attributes, and as its form data name. Uses the default defined in Server if null. Only change this if you’re using a custom CSRF middleware.

$logger : LoggerInterface|null = null

A logger.

Return values
mixed —

setLogger()

public setLogger(LoggerInterface $logger) : void
Parameters
$logger : LoggerInterface
Return values
void —

showForm()

Show Form

public showForm(ServerRequestInterface $request, array<string|int, mixed> $authenticationResult, string $formAction, mixed $clientHAppOrException) : ResponseInterface

This method is called once the IndieAuth Authorization Endpoint has confirmed that:

  • The current user is authenticated
  • The client app (client_id) has been fetched and is valid
  • The client app redirect_uri is known to be valid

It should build an authorization form which the currently logged-in user can use to choose which scopes (if any) to grant the app.

Information specific to the IndieAuth authorization request can be found in $request->getQueryParams(). The parameters most likely to be of use to the authorization form are:

  • scope: a space-separated list of scopes which the client app is requesting. May be absent.
  • client_id: the URL of the client app. Should be shown to the user. This also makes a good “cancel” link.
  • redirect_uri: the URI which the user will be redirected to on successful authorization.

The form MUST submit a POST request to $formAction, with the taproot_indieauth_action parameter set to approve.

The form MUST additionally include any CSRF tokens required to protect the submission. Refer to whatever CSRF protection code you’re using (e.g. DoubleSubmitCookieCsrfMiddleware) and make sure to include the required element. This will usually involve getting a CSRF token with $request->getAttribute() and including it in an <input type="hidden" …/>.

The form SHOULD offer the user the opportunity to choose which of the request scopes, if any, they wish to grant. It should describe what effect each scope grants. If no scopes are requested, tell the user that the app is only requesting authorization, not access to their data.

The form MAY offer the user UIs for additional token configuration, e.g. a custom token lifetime. You may have to refer to the documentation for your instance of TokenStorageInterface to ensure that lifetime configuration works correctly. Any other additional data is not used by the IndieAuth library, but, if stored on the access token, will be available to your app for use.

Server adds the following headers to the response returned from showForm():

Cache-Control: no-store
Pragma: no-cache
X-Frame-Options: DENY
Content-Security-Policy: frame-ancestors 'none'

These headers prevent the authorization form from being cached or embedded into a malicious webpage. It may make sense for you to add additional Content-Security-Policy values appropriate to your implementation, for example to prevent the execution of inline or 3rd party scripts.

Parameters
$request : ServerRequestInterface

The current request.

$authenticationResult : array<string|int, mixed>

The array returned from the Authentication Handler. Guaranteed to contain a 'me' key, may also contain additional keys e.g. 'profile'.

$formAction : string

The URL which your form MUST submit to. Can also be used as the redirect URL for a logout process.

$clientHAppOrException : mixed
Return values
ResponseInterface —

A response containing the authorization form.

transformAuthorizationCode()

Transform Authorization Code

public transformAuthorizationCode(ServerRequestInterface $request, array<string|int, mixed> $code) : array<string|int, mixed>

This method is called on a successful authorization form submission. The $code array is a partially-constructed authorization code array, which 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.

This method should add any additional data to the auth code, before it is persisted and returned to the client app. Typically, this involves setting the scope key to be a valid space-separated scope string of any scopes granted by the user in the form.

If the form offers additional token configuration, this method should set any relevant keys in $code based on the form data in $request.

Parameters
$request : ServerRequestInterface

The current request.

$code : array<string|int, mixed>

The base authorization code data, to be added to.

Return values
array<string|int, mixed> —

The $code data after making any necessary changes.

Search results