Payload CMS 2FA

A lightweight two-factor authentication plugin for Payload CMS.

Built and maintained by AssamLabs.

📖 Read the complete documentation: AssamLabs Docs

🔐 Built on Payload CMS security: Payload 2FA integrates with Payload CMS's native authentication and security system, giving you a straightforward way to add two-factor authentication without replacing your existing authentication setup.

⚡ One of the easiest ways to add 2FA to Payload CMS: Install the plugin, configure your authentication collection, and you're ready to enable two-factor authentication.

Features

• TOTP-based two-factor authentication
• QR code setup with authenticator apps
• Backup codes for account recovery
• Enable and disable 2FA from the Payload Admin Panel
• Protected authentication flow
• Custom login interface
• Admin UI for managing 2FA
• Support for custom authentication collections
• Automatic login protection through Payload hooks
• Configurable TOTP issuer

Installation

1. Create a User for a New Payload App

If you are installing Payload CMS 2FA in a completely new Payload CMS application, make sure at least one user already exists and can log in normally before installing the plugin.

This is only required for a fresh Payload CMS setup.

2. Install the Package

Install the package using your preferred package manager:

pnpm add @assamlabs/payload-2fa

3. Add the Plugin

Add the plugin to your Payload configuration:

import { twoFactorAuth } from "@assamlabs/payload-2fa";

export default buildConfig({
  // ...

  plugins: [twoFactorAuth()],
});

Payload 2FA uses the users collection by default.

Required Environment Variable

The plugin requires an internal authentication secret:

PAYLOAD_2FA_INTERNAL_SECRET=your-secure-random-secret

Keep this value private and do not expose it to the client.

Custom Authentication Collection

You can use a different authentication-enabled collection:

twoFactorAuth({
  collectionSlug: "members",
});

4. Generate the Import Map

After completing your Payload configuration, generate the Payload Admin import map:

pnpm payload generate:importmap

Note: If your development server is already running, stop it before generating the import map and start it again afterward.

5. Start Your Payload Application

Once the configuration and import map are complete, start your Payload application:

pnpm dev

Quick Start

After installation:

1. Open the user document in the Payload Admin Panel.
2. Enable Two-Factor Authentication.
3. Scan the generated QR code with your authenticator app.
4. Verify the generated code.
5. Save your backup codes.
6. Log out and test the 2FA login flow.

Requirements

• Payload CMS 3.x
• Node.js 18.20.2+ or 20.9+
• React 19

Documentation

Full documentation is available at AssamLabs Docs.

License

GPL-3.0-only