schmarty

belding

A single-user password-protected IndieAuth server providing auth, token, introspection, and metadata endpoints. Built on PHP using taproot/indieauth.

Go to file

Marty McGuire a5835b8816 WIP: oauth client id metadata patched into taproot		1 week ago
app	some WIP dashboard stuff	3 weeks ago
data	ignore data/logs/	2 years ago
lib	configurize token ttl	2 years ago
public	some WIP dashboard stuff	3 weeks ago
templates	WIP: oauth client id metadata patched into taproot	1 week ago
.gitignore	quick and dirty wiring up of indieauth routes	2 years ago
LICENSE	LICENSE and README.md	2 years ago
README.md	apache fixup	2 years ago
composer.json	WIP: oauth client id metadata patched into taproot	1 week ago
composer.lock	WIP: oauth client id metadata patched into taproot	1 week ago

README.md

Belding

A minimal single-site, single-user IndieAuth implementation built on PHP using Taproot/IndieAuth at its core.

Quick (& Dirty) Start

How to run your own instance of Belding.

You'll need a web server with PHP 7.x or greater and Composer 2.

Use git to clone this repository.

In the project folder, run composer install to install dependencies.

Copy lib/config.template.php to lib/config.php and edit it to your liking.

Run the dev server:

$ php -S localhost:3000 -t public

A test request should show the contents of the homepage. With the default config, you'll need to preface all requests with /api/indieauth:

$ curl localhost:3000/api/indieauth
<h1>Hello, World!</h1>

Further testing is out of the scope of this document. Make sure the user you are running php as has permission to write to the project's data/ folder.

Deployment

Belding expects a web server like nginx or Apache to act as a proxy, handle HTTPS, etc.

An example Apache 2.4 configuration with mod-php (sorry) that will "mount" the app at /api/indieauth on an existing VirtualHost:

# ...

Alias /api/indieauth /path/to/belding/public
<Directory /path/to/belding/public>
	Require all granted
	RewriteEngine On
	RewriteCond %{REQUEST_FILENAME} !-f
	RewriteCond %{REQUEST_FILENAME} !-d
	RewriteRule ^.*$ index.php [QSA,L]
	<Files index.php>
		Options +ExecCGI
	</Files>
</Directory>

# ...

You'll need to ensure that $contextPath in lib/config.php matches /api/indieauth.

Server Configuration

Server configuration happens in lib/config.php. By default:

Storage:
- token data is stored in the project's data/auth_tokens/ folder. Make sure this folder is writable by the web server or php-fpm user.
- logs are stored in data/logs/
IndieAuth options:
- PKCE, though required by the spec, is off by default to support legacy IndieAuth clients.
- Tokens do not expire by default.
Secrets:
- $tokenAndCookieSecret
  - used to sign token and cookie data to prevent tampering. must be at least 64-characters long.
  - you can generate something with openssl rand -base64 46
- $tokenIntrospectSecret
  - a shared secret used by relying parties like your Micropub endpoint when the need to verify a token.
  - generate with something like openssl rand -base64 46
- $passHash
  - the hash of the password you will use to sign in to this server.
  - generate from within PHP (php -a) with password_hash('your strong password', PASSWORD_DEFAULT).

Website Configuration

You'll need to configure your homepage to add some HTTP Link headers or HTML <link> headers so that IndieAuth clients can discover your server setup.

For example, you could add a block like this to the <head> of your homepage:

<link rel="indieauth-metadata" href="https://example.com/api/indieauth/metadata"  />
<link rel="authorization_endpoint" href="https://example.com/api/indieauth/auth"  />
<link rel="token_endpoint" href="https://example.com/api/indieauth/token"  />

Form Customization

Although you are the only person who will ever have to look at it, you may want to update the files in templates/ to your liking.

Currently the server piggybacks off of Taproot/indieauth's template system which simply includes these PHP files. You can use that to extend these with common header/footer template content if you wish.

You may also want to share CSS between the templates by creating a CSS file in the project's public/ folder (e.g. public/css/style.css) and including it in the <head> section of each template file.

Notes on Token Verification

This project supports the token introspection endpoint as defined in the spec using a Bearer token method to let the server know that the relying app (like your Micropub endpoint) is allowed to verify tokens.

If your relying app knows how to use the token introspection endpoint, you'll need to configure it with the shared $tokenIntrospectSecret from your config.

To support older IndieAuth clients that do not support the introspection endpoint, this server supports the less secure verification method of making GET requests to the token endpoint with the token in an Authorization header.

Known Issues

Although the IndieAuth spec notes that fetching client_id is optional, Taproot/IndieAuth will hard error if it cannot fetch the URL defined by client_id for any reason.

Similarly, Taproot/IndieAuth will hard-error if client_id is not a "complete" URL. For example if it is missing path information. This project works around that by applying URL canonicalization to the client_id before passing it to Taproot/indieauth.

Possible Future Work

Nicer default templates.
Support auth methods other than a single password.
Admin features like browsing and revoking issued tokens.
Multiple user support.
Support token storage via SQLite3 (or your DB of choice).
Refactor so this project could be more easily integrated into a larger PHP PSR-7 web app.
More IndieAuth features from indieauth-metadata definition:
- Token revocation
- Configurable list of scopes supported
- Userinfo endpoint
- Refresh tokens

License

Initial contents of templates/ derived from Taproot/indieauth.