Payload TOTP (Time-based One-Time Password)

!banner


If you find this plugin useful, consider supporting its development through donations. Your contributions help improve security and stability!

What Does This Plugin Do?

TOTP is a widely used authentication mechanism that generates a unique, time-sensitive code based on a shared secret and the current time. This code is typically used as a second factor in authentication (2FA), adding an extra layer of security to protect against unauthorized access.

This plugin enhances security by wrapping the existing access controls under a TOTP verification process. Users must enter a valid TOTP code generated by an authenticator app (such as Google Authenticator, Authy, or Microsoft Authenticator) to gain access, reducing the risk of unauthorized logins even if credentials are compromised.

Core Features

- Seamlessly integrates with existing access controls.
- Full internationalization (i18n) support for all UI elements.
- Built-in support for both dark and light themes.
- Compatible with API key authentication.
- Works with any authentication strategy supported by PayloadCMS.

Installation

Install the plugin using any JavaScript package manager like pnpm, npm, or Yarn:

``terminal
pnpm add payload-totp
`

Basic Usage

In the plugins array of your Payload Config, call the plugin with options:

`tsx
import { buildConfig } from 'payload'
import { payloadTotp } from 'payload-totp'

const config = buildConfig({
collections: [
{
slug: 'users',
auth: true,
fields: [],
},
],
plugins: [
payloadTotp({
collection: 'users',
// see below for a list of available options
}),
],
})

export default config
`

__IMPORTANT__: The plugin overrides all collections, therefore it should be the last plugin in the array, or at least not followed by plugins that add collections/globals. Furthermore, the plugin can break the default behavior for non–user-based access. Please read the Access Wrapper section.

Now, you need to modify the middleware.ts or create it if doesn't exist. The middleware will pass the pathname as a header. This is necessary because we don't have access to the pathname in the server-side component. Without this part, it will create an endless redirect loop.

`ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
const pathname = request.nextUrl.pathname
const response = NextResponse.next()

response.headers.append('x-pathname', pathname)

return response
}
`

Options

$3

The collection property specifies which collection with auth enabled should have TOTP protection. Currently, the plugin supports TOTP for a single collection at a time.

$3

Allows you to conditionally disable the plugin based on runtime conditions.

$3

By default, the plugin does not force users to configure TOTP. The TOTP verification will only be prompted if the user has configured it. This option forces all users to configure their TOTP after login, enhancing security by ensuring 2FA is enabled for all accounts.

$3

The disableAccessWrapper property disables the default access wrapper for all collections and globals. Read more about it.

$3

The totp property is used to configure the TOTP class from the otpauth package. You can customize the following options:

- algorithm: The hash algorithm to use (e.g. 'SHA1', 'SHA256', 'SHA512')
- digits: Number of digits in the generated token (default: 6)
- issuer: The issuer name to display in authenticator apps
- period: Token validity period in seconds (default: 30)

$3

When enabled, the QR code shown on the setup page is rendered with a white background to improve readability when using a dark theme. Disabled by default.

Access Wrapper

By default, PayloadCMS has access set to ({user}) => Boolean(user). Since PayloadCMS naturally handles access for logged-in users, this plugin follows the same pattern.

The plugin will override the provided access function. This means that TOTP verifications will be called first, and if successful, it will then call the original function and return its result. This approach ensures compatibility with role-based access control and other custom access patterns.

There are cases where collections or globals need to be available for non-logged-in users. To handle this, the plugin provides disableAccessWrapper globally or per global/collection. If you have many collections/globals that provide custom access or public access, you should use the plugin options disableAccessWrapper.

In case of changing the default access, you can deactivate per collection/global:

`tsx
import type { CollectionConfig } from 'payload'

export const posts: CollectionConfig = {
slug: 'posts',
access: {
read: () => true,
},
fields: [],
custom: {
totp: {
disableAccessWrapper: {
read: true,
},
},
},
}
`

The disableAccessWrapper from custom has the same type as access in Collection/Global based on the context.

In case that you need a more complex access, for example based on a header or auth user, you can import totpAccess:

`tsx
import type { CollectionConfig } from 'payload'
import { totpAccess } from 'payload-totp'

export const posts: CollectionConfig = {
slug: 'posts',
admin: {
useAsTitle: 'title',
},
access: {
read: (args) => {
return (
args.req.headers.get('authorization') === 'Bearer 123' ||
totpAccess(({ req: { user } }) => Boolean(user))(args)
)
},
},
fields: [],
custom: {
totp: {
disableAccessWrapper: {
read: true,
},
},
},
}
`

Dashboard Walkthrough

After logging in, navigate to your account settings where you'll find the "Authenticator app" field. If forceSetup` is enabled, you'll be automatically redirected to the Setup TOTP page.

!show_auth_field

Click the "Setup" button to proceed to the Setup TOTP Page:

!setup_page

Scan the QR code or copy the secret into your preferred authenticator app, then enter the generated PIN code.

!setup_video

Upon successful verification, you'll be redirected back to your account page.

Now, when you log out and log back in, you'll be prompted to enter your TOTP PIN code:

!login_video

After entering the correct PIN, you'll be redirected to the main dashboard page.