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
Records 2FA activity in the audit log when flarum/audit is enabled

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

Recovering a locked-out account

If a user, for example an admin, loses both their authentication device and their backup codes, disable 2FA for them from the CLI. Pass a username, email address or user ID:

php flarum twofactor:disable <user>

Add --force to skip the confirmation prompt. The user is notified, and if one of their groups requires 2FA they will be asked to set it up again.

Users with the "Manage 2FA for other users" permission can also disable 2FA for another user from that user's security page, including users whose groups require 2FA.

Audit log

When flarum/audit is enabled, these actions are recorded:

user.two_factor_enabled: a user enabled 2FA
user.two_factor_disabled: 2FA was disabled, by the user or by someone allowed to manage 2FA for others
user.two_factor_device_changed: a user moved 2FA to a new device
user.two_factor_backup_code_used: a backup code was used (payload includes how many remain)
group.two_factor_required / group.two_factor_not_required: an admin changed whether a group requires 2FA

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.

Support

Please consider supporting my extension development and maintenance work.

ianm / twofactor

Package info

Security

Fund package maintenance!

Statistics