Two-factor authentication

A second factor means a stolen or guessed password is not enough to get in. FluentAuth supports three methods and applies them per role, so administrators can be required to use one while subscribers are never asked.

Methods

A usable passkey is offered ahead of an authenticator app. Enrolled device methods take priority over email. A magic link already proves access to the mailbox, so it skips an email code but does not satisfy a required device factor.

Settings

Under Settings → General Settings → Two-Factor Authentication:

A role can be in both email and authenticator lists. Users in that role get email codes until they enrol an app, then app codes.

Enrolling an authenticator

Users enrol from their own profile (Users → Profile → Two-Factor Authentication), or from the standalone setup page at wp-login.php?action=fls_2fa_setup, which works without wp-admin access. Enrolment is:

1. Scan the QR code, or type the secret into the app by hand.
2. Enter the current six-digit code to prove the app is set up.
3. Save the ten recovery codes shown once. Each works one time in place of an app code.

The QR code is drawn by the plugin itself. Nothing about the secret leaves your server.

Encrypting stored secrets

An authenticator secret is the one credential FluentAuth has to be able to read back, because a code is checked by generating it. It cannot be hashed the way a password or a recovery code is. So it can be encrypted instead, with a key you keep out of the database:

1. Add FLUENT_AUTH_SECURITY_KEY to wp-config.php. Any long random string will do.
2. Turn Encrypt stored secrets on under the authenticator app settings.

Existing enrolments are encrypted in place, and a copy of your database stops being enough to generate anybody’s codes. If the key later goes missing or changes, FluentAuth says which of the two happened and both are recoverable while you still have the old value. See Constants.

What the user sees

After a correct password, a second screen asks for the code. Five wrong codes end the attempt, and a pending challenge expires after ten minutes. Both outcomes are logged.

Users whose role is in Roles that must set one up and who have not enrolled are shown the setup page instead of the dashboard until they do. Users whose role may enrol but is not required see a one-time nudge after login, dismissible; the fluent_auth/ask_to_set_up_totp filter turns that off.

Managing enrolments

Settings → 2FA Enrollment lists every user in an eligible role with whether they have an device methods, searchable and filterable. Review the enrolled methods and reset the affected method for someone who has lost access. Passkeys can also be managed from the user profile.

Logins that skip the form

The second factor is also enforced for logins that never show the login form: application passwords, social logins, and code that calls wp_set_auth_cookie() directly. A user whose role requires a factor cannot get a session without one by any route. To exempt a specific integration, use the fluent_auth/enforce_2fa_on_auth_cookie filter.

WP-CLI is exempt, so wp user session create and similar still work from the server.

Recovery

• Lost the phone: use a recovery code, then reset and re-enrol from the profile.
• Lost the phone and the codes: another administrator resets you from 2FA Enrollment.
• Only administrator, lost everything: see Troubleshooting for the server-access recovery procedure.

Developer hooks