payload-totp
Version:
Add an extra security layer to PayloadCMS using a Time-based One-time Password (TOTP).
189 lines (135 loc) • 7.81 kB
Markdown
# Payload TOTP (Time-based One-Time Password)
[](https://www.npmjs.com/package/payload-totp)
[](https://www.npmjs.com/package/payload-totp)
[](https://github.com/sponsors/GeorgeHulpoi)
[](https://www.linkedin.com/in/george-hulpoi/)
[](https://x.com/GeorgeHulpoi)
[](https://en.george-hulpoi.dev/blog)
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](https://pnpm.io/), [npm](https://npmjs.com/), or [Yarn](https://yarnpkg.com/):
```terminal
pnpm add payload-totp
```
## Basic Usage
In the plugins array of your [Payload Config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#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.
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
### `collection`
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.
### `disabled`
Allows you to conditionally disable the plugin based on runtime conditions.
### `forceSetup`
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.
### `disableAccessWrapper`
The `disableAccessWrapper` property disables the default access wrapper for all collections and globals. [Read more about it](#access-wrapper).
### `totp`
The `totp` property is used to configure the [TOTP class](https://hectorm.github.io/otpauth/classes/TOTP.html) 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)
### `forceWhiteBackgroundOnQrCode`
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](#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.
Click the "Setup" button to proceed to the Setup TOTP Page:
Scan the QR code or copy the secret into your preferred authenticator app, then enter the generated PIN code.
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:
After entering the correct PIN, you'll be redirected to the main dashboard page.