README

A PSR-7-compatible implementation of the request-handling logic for IndieAuth authorization endpoints and token endpoints.

Installation

taproot/indieauth is currently tested against and compatible with PHP 7.3, 7.4, and 8.0.

Install taproot/indieauth using composer:

composer.phar require taproot/indieauth
composer.phar install (or composer.phar update)

Versioned releases are GPG signed so you can verify that the code hasn’t been tampered with.

gpg --recv-keys 1C00430B19C6B426922FE534BEF8CE58118AD524
cd vendor/taproot/indieauth
git tag -v v0.1.0 # Replace with the version you have installed

Usage

Typical minimal usage looks something like this:

// Somewhere in your app set-up code:
$server = new Taproot\IndieAuth\Server([
	// A secret key, >= 64 characters long.
	'secret' => YOUR_APP_INDIEAUTH_SECRET,

	// A path to store token data, or an object implementing TokenStorageInterface.
	'tokenStorage' => '/../data/auth_tokens/',

	// An authentication callback function, which either returns data about the current user,
	// or redirects to/implements an authentication flow.
	'authenticationHandler' => function (ServerRequestInterface $request, string $authenticationRedirect, ?string $normalizedMeUrl) {
		// If the request is authenticated, return an array with a `me` key containing the
		// canonical URL of the currently logged-in user.
		if ($userUrl = getLoggedInUserUrl($request)) {
			return ['me' => $userUrl];
		}
		
		// Otherwise, redirect the user to a login page, ensuring that they will be redirected
		// back to the IndieAuth flow with query parameters intact once logged in.
		return new Response('302', ['Location' => 'https://example.com/login?next=' . urlencode($authenticationRedirect)]);
	}
]);

// In your authorization endpoint route:
return $server->handleAuthorizationEndpointRequest($request);

// In your token endpoint route:
return $server->handleTokenEndpointRequest($request);

// In another route (e.g. a micropub route), to authenticate the request:
// (assuming $bearerToken is a token parsed from an “Authorization: Bearer XXXXXX” header
// or access_token property from a request body)
if ($accessToken = $server->getTokenStorage()->getAccessToken($bearerToken)) {
	// Request is authenticated as $accessToken['me'], and is allowed to
	// act according to the scopes listed in $accessToken['scope'].
	$scopes = explode(' ', $accessToken['scope']);
}

Refer to the __construct documentation for further configuration options, and to the documentation for both handling methods for further documentation about them, specifically:

Taproot\IndieAuth\Server::__construct() for detailed information about how to configure your Server instance.
Taproot\IndieAuth\Server::handleAuthorizationEndpointRequest() for an overview of exactly what happens during an authorization request (which is the bulk of what this library is for)
Taproot\IndieAuth\Callback\DefaultAuthorizationForm (and its associated template) for details about customising the default consent screen form.
Taproot\IndieAuth\Callback\SingleUserPasswordAuthenticationCallback for an example of how to implement an authentication callback, and it’s corresponding template for information on customising the template.
Taproot\IndieAuth\Storage\TokenStorageInterface for details about implementing your own token storage
Taproot\IndieAuth\Callback\AuthorizationFormInterface for infomation about implementing your own authorization form.

Example Application

See the taproot/micropub example app for a working example of how to use taproot/indieauth.

Contributing

If you have any questions about using this library, join the indieweb chatroom and ping barnaby.

If you find a bug or problem with the library, or want to suggest a feature, please create an issue.

If discussions lead to you wanting to submit a pull request, following this process, while not required, will increase the chances of it quickly being accepted:

Fork this repo to your own github account, and clone it to your development computer.
Run ./run_coverage.sh and ensure that all tests pass — you’ll need XDebug for code coverage data.
If applicable, write failing regression tests e.g. for a bug you’re fixing.
Make your changes.
Run ./run_coverage.sh and open docs/coverage/index.html. Make sure that the changes you made are covered by tests. taproot/indieauth had nearly 100% test coverage from version 0.1.0, and that number should never go down!
Run ./vendor/bin/psalm and and fix any warnings it brings up.
Install and run ./phpDocumentor.phar to regenerate the documentation if applicable.
Push your changes and submit the PR.

Changelog

v0.1.0 2021-06-24

taproot / indieauth

Maintainers

Details