Overview
Add secure TOTP-based two-factor authentication to Payload CMS.
Payload 2FA
Add two-factor authentication to Payload CMS with a simple plugin.
Payload 2FA integrates directly with your authentication collection and Payload Admin Panel to provide a complete TOTP-based authentication flow using Payload's native authentication system.
Payload 2FA works with your existing authentication collection. You can use
the default users collection or configure a different authentication
collection.
Features
TOTP Authentication
Protect accounts with time-based one-time passwords from authenticator applications.
QR Code Setup
Set up two-factor authentication by scanning a QR code with an authenticator app.
Backup Codes
Generate backup codes for account recovery when an authenticator application is unavailable.
Protected Login
Require a second authentication factor when 2FA is enabled.
Custom Collections
Use your own authentication collection instead of being restricted to users.
Payload Admin
Enable and manage two-factor authentication directly from the Payload Admin Panel.
How It Works
Payload 2FA adds the fields, login protection, authentication endpoints, and Admin Panel interface required for two-factor authentication.
Sign In
The user enters their email address and password through the Payload 2FA login form.
2FA Verification
If 2FA is enabled for the account, the user must provide an authenticator code or backup code.
Verify the Code
Payload 2FA validates the submitted TOTP or backup code.
Complete Authentication
After successful verification, authentication is completed and the user can access the Payload Admin Panel.
Users who have not enabled 2FA can continue to use the normal email and password authentication flow.
Authentication Methods
Payload 2FA supports two methods for completing the second authentication step.
Authenticator Code
Users can enter the time-based one-time password generated by a TOTP-compatible authenticator application.
Common applications include:
- Google Authenticator
- Microsoft Authenticator
- Authy
- 1Password
- Other TOTP-compatible applications
Backup Code
Users can use a backup code instead of an authenticator code when their authenticator application is unavailable.
Each backup code can only be used once.
Backup codes are shown only when they are generated. Store them securely and do not share them with anyone.
Login Behavior
When 2FA is enabled for a user, authentication must be completed through the Payload 2FA login flow.
Direct API-based login does not complete authentication for users with 2FA enabled.
Users who have not enabled 2FA can continue to use Payload's normal API login flow.
This restriction applies to authentication. Payload's other APIs continue to work normally after a user is authenticated.
Requirements
Before installing Payload 2FA, make sure your project has:
- Payload CMS 3.x
- An authentication-enabled collection
- Node.js supported by your Payload version
- pnpm, npm, or yarn
- A TOTP-compatible authenticator application
For a completely new Payload CMS project, create at least one user and make sure that user can log in normally before setting up 2FA.
Configuration
Payload 2FA uses the users collection by default.
For a custom authentication collection, configure collectionSlug:
twoFactorAuth({
collectionSlug: "members",
});You can also configure the issuer displayed by authenticator applications:
twoFactorAuth({
issuer: "AssamLabs",
});The default issuer is Payload2FA.
The PAYLOAD_2FA_INTERNAL_SECRET environment variable is required for the
authentication flow. See the Installation guide for setup instructions.
Installation
For installation instructions, including the required environment variable and Payload Admin import map generation, see the installation guide.
Installation
Install Payload 2FA, configure the required secret, and generate the import map.
Quick Start
Enable 2FA for a user and complete your first authentication setup.
Configuration
Configure the authentication collection and TOTP issuer.
Last updated on