Installation

Install Payload 2FA in your Payload CMS project and add it to your Payload configuration.

Before You Install

If you are installing Payload 2FA in a completely new Payload CMS project, create at least one user using Payload's standard Create First User setup before installing the plugin.

Make sure the first user can successfully sign in to the Payload Admin Panel before installing Payload 2FA.

Install the Package

Install the plugin using your preferred package manager.

pnpm add @assamlabs/payload-2fa

Configure the Internal Secret

Payload 2FA requires an internal authentication secret to complete its authentication flow.

Add the following variable to your environment:

PAYLOAD_2FA_INTERNAL_SECRET=your-secure-random-secret

Use a strong, unpredictable value and keep it private.

PAYLOAD_2FA_INTERNAL_SECRET is required for Payload 2FA to work. Do not expose it to the client or commit it to source control.

Add the Plugin

Import twoFactorAuth from @assamlabs/payload-2fa and add it to the plugins array in your Payload configuration.

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

export default buildConfig({
  collections: [
    // Your collections
  ],

  plugins: [twoFactorAuth()],
});

By default, Payload 2FA uses the users collection as the authentication collection.

Your users collection must be configured with auth: true.

Using a Custom Authentication Collection

If your application uses a different authentication collection, pass its collection slug to the plugin.

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

The specified collection must exist in your Payload configuration and have authentication enabled.

For example:

export default buildConfig({
  collections: [
    {
      slug: "members",
      auth: true,
      fields: [
        // Your fields
      ],
    },
  ],

  plugins: [
    twoFactorAuth({
      collectionSlug: "members",
    }),
  ],
});

Generate the Import Map

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

If your development server is currently running, stop it before generating the import map.

pnpm payload generate:importmap

Generate the import map after adding and configuring Payload 2FA so the plugin's Admin Panel components are included.

Generate the Migration

Payload 2FA adds fields to your authentication collection, so you must create a migration after adding and configuring the plugin.

Create the migration:

pnpm payload migrate:create

Review the generated migration and commit it to your project.

Creating the migration is important for production deployments. The generated migration contains the database changes required by Payload 2FA and can be applied when deploying your application.

If your development environment does not automatically apply migrations, you can apply the migration manually:

pnpm payload migrate

You do not need to run pnpm payload migrate manually when your development setup already applies migrations automatically.

Start Your Development Server

After generating the import map and migration, start your development server:

pnpm dev

If your development server was already running, make sure it is stopped before generating the import map, then start it again.

Verify the Installation

Once the server has restarted, open your Payload Admin Panel.

Navigate to an authenticated user in your configured collection.

You should see the Two-Factor Authentication section on the user document.

From there, you can enable 2FA and begin the setup process.

The 2FA section is only intended for the currently authenticated user. It will not be displayed as an account setup interface for other users.

Last updated on

Installation

On this page