Configuration

Payload 2FA provides configuration options that allow you to adapt the plugin to your Payload CMS application.

Plugin Configuration

Add twoFactorAuth to the plugins array in your Payload configuration:

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

export default buildConfig({
  plugins: [twoFactorAuth()],
});

By default, Payload 2FA uses the users collection and Payload2FA as the TOTP issuer.

Authentication Collection

Payload 2FA can work with any authentication-enabled Payload collection.

Default Collection

If your application uses the default users collection, no additional configuration is required:

twoFactorAuth();

This is equivalent to:

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

Custom Collection

If your authentication collection uses a different slug, specify it using collectionSlug.

For example, if your authentication collection is members:

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

The specified collection must have Payload authentication enabled.

Payload 2FA does not require your authentication collection to be named users. Use collectionSlug when your application uses a different collection name.

TOTP Issuer

The issuer option controls the name displayed by authenticator applications for accounts generated by Payload 2FA.

By default, the issuer is:

Payload2FA

You can provide your own issuer to match your application or organization:

twoFactorAuth({
  issuer: "AssamLabs",
});

The issuer is used when generating the TOTP configuration and appears as the service name in the user's authenticator application.

Choose an issuer name that your users will recognize. Changing the issuer does not change the user's secret, but it can change how the account is displayed in an authenticator application.

Complete Example

The following example configures Payload 2FA for a custom members collection and uses a custom issuer:

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

import { Members } from "./collections/Members";

export default buildConfig({
  collections: [Members],

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

Configuration Options

Option	Type	Default	Description
`collectionSlug`	`string`	`"users"`	The slug of the authentication-enabled collection used by Payload 2FA.
`issuer`	`string`	`"Payload2FA"`	The name displayed by authenticator applications for TOTP accounts generated by Payload 2FA.

Important

The collection specified by collectionSlug must:

Exist in your Payload configuration.
Have authentication enabled.
Contain users who can authenticate through Payload.

If the configured collection cannot be found, Payload 2FA will throw an error during configuration.

When adding Payload 2FA to an existing application, use the slug of your existing authentication collection instead of creating or renaming a collection just for 2FA.

Last updated on

Configuration

On this page