README

A Flarum extension. 2FA for Flarum

Requirements

This extension requires a minimum of PHP 8.1, due to a 3rd party library constraint.

Features

• Enforces admin accounts to have 2FA enabled for increased security
• Configure which additional user groups should also be enforced
• Supports all common authentication apps
• Protects login, forgot password endpoints
• Integrates with fof/oauth to protect OAuth logins to protected accounts
• 2FA Enabled/Disabled notifications
• 2FA Status page
• Backup/recovery codes
• Option to revoke dormant access tokens after X days of no usage

Permissions

This extension provides the ability to view the status of 2FA of other users (intended for admin and/or moderator use). In order for this to function correctly, you must also set the permission Moderate Access Tokens to at least the same group as you require for View 2FA status of other users.

Installation

Install with composer:

composer require ianm/twofactor:"*"

Updating

composer update ianm/twofactor
php flarum migrate
php flarum cache:clear

Usage

CLI

Independantly of the setting, you may remove dormant access tokens using the CLI. The days setting defaults to 30 days, and the CLI will still respect this value from the extension settings, as well as the developer token setting:

php flarum twofactor:kill-inactive-tokens

TODO

Screenshots

QR Code setup

Manual setup

Security tab integration

Enabled/Disabled notifications

Admin user list status icon

Extensibility

Disabling 2FA for specific OAuth providers

If you are building an extension that integrates with fof/oauth and want certain providers to bypass the 2FA challenge entirely, use the TwoFactor extender in your extension's extend.php. Wrap it in a Conditional so it only activates when ianm/twofactor is enabled:

use Flarum\Extend\Conditional;
use IanM\TwoFactor\Extend\TwoFactor;

return [
    // ...
    (new Conditional())
        ->whenExtensionEnabled('ianm-twofactor', fn () => [
            (new TwoFactor())->disable('my-oauth-provider'),
        ]),
];

The provider name must match the string identifier used when registering the provider with fof/oauth (e.g. 'github', 'google', 'discord'). Multiple providers can be chained:

(new Conditional())
    ->whenExtensionEnabled('ianm-twofactor', fn () => [
        (new TwoFactor())
            ->disable('github')
            ->disable('google'),
    ]),

Note: This only bypasses the OAuth 2FA interception. Users who log in directly (username + password) are unaffected and will still be required to complete 2FA if it is enabled on their account.

Links

• Packagist
• GitHub
• Discuss

Support

Please consider supporting my extension development and maintenance work.