Download the PHP package liplum/flarum-jwt-auth without Composer

Flarum JSON Web Token Auth

A Flarum extension to authenticate based on JSON Web Token (JWT) token through HTTP request cookie.

Get Started

Installation:

Update:

Forum Setup

Setup the JWT authentication by following the steps below in the extension settings page. You can find the corresponding backend implementation example in the next chapter.

1. Set the cookie name

Set the name of cookie from the user browser requests. For example, "access_token".

2. Set the JWT audience

It's optional.

The extension will check if the aud field in JWT payload is identical to the JWT audience provided by admin settings. If not, the JWT will be considered as invalid.

3. Set the JWT secret

The secret to sign(encode) and verify(decode) a JWT token.

The JWT payload should be something like this.

For security issue, you should set the JWT secret in the config.php instead of barely display on extension settings page for anyone who has the extension management permission.

4. Set the JWT Signing Algorithm

It's optional.

It's "HS256" by default, by following the default option from the jsonwebtoken package.

5. Set the registration hook URL

The hook which will be called for new Flarum users.

The payload of the hook request is in JSON:API which Flarum uses, and the authentication can be checked via the Authorization header.

Here is something like the Flarum backend would request the hook:

And the backend should handle the registration request and respond a the user attributes in JSON:API:

These attributes will be passed internally to POST Flarum "/api/users", so any attribute added by other extensions can also be provided.

By default, all accounts will be automatically enabled. You can change this behavior by returning "isEmailConfirmed": false attributes in the registration hook.

6. Set the Authorization Header

It's optional.

If the field is left empty, the Authorization header will be "Token {jwt}".

Otherwise, the field will be directly sent as Authorization header without any modification.

Here is something like the evaluation process:

For security issue, you should set the Authorization header in the config.php instead of barely display on extension settings page for anyone who has the extension management permission.

Backend Setup

Taking the express.js backend server as an example, you can set up the following routes.

Hidden Iframe

The hidden iframe offers a way to refresh the cookie in the background and optionally to provide auto login.

If the hidden iframe setting is set, the given URL will be loaded in a 0x0 iframe placed outside the browser viewport.

The iframe can use window.postMessage to inform Flarum of a change in the session state. The message can be sent at any time and any number of times. You can use a loop repeatedly sending the current state if necessary.

Flarum will check for a change in the reported state and prompt the user to refresh the page if it changes.

If {jwtSessionState: 'login'} is sent while Flarum is logged out, Flarum will say the user has been automatically logged in and may refresh the page.

If {jwtSessionState: 'logout'} is sent while Flarum is logged in, Flarum will say the session has expired and the user may refresh the page.

If the time elapsed between Flarum boot and the postMessage is smaller than the configured "Auto Login Delay", the page will refresh without user interaction.

Switching user without going through logout state is current not supported.

Code example for the iframe:

The last parameter should be set to the Flarum origin. '*' can also be used but isn't recommended.

Additional Reading

An admin user is used internally to call the REST API that creates new Flarum users. By default, user with ID 1 will be used but this can be customized in the admin settings. The value must be the Flarum ID (MySQL auto-increment) and not the JWT subject ID.

Users can be edited via their JWT subject ID by using the PATCH /api/jwt/users/<sub> endpoint. It works exactly the same way as PATCH /api/users/<id> but takes the JWT subject ID instead of Flarum ID.

Under the hood

Users are matched through the jwt_subject column in the database that is matched to the token's sub value.

The original Flarum session object (Symfony session) and cookie are not used for stateless authentication, however the cookie session is kept because Flarum and some extensions cannot work without it.

This session object is not invalidated during "login" and "logout" of the stateless JWT authentication, so there could be issues with extensions that rely on that object for other purposes than validation messages.

Acknowledgement

Thanks to https://github.com/clarkwinkelmann/flarum-ext-jwt-cookie-login with MIT License Copyright (c) 2022 Clark Winkelmann.