Use passkeys with Payload CMS through payload-passkey

I released payload-passkey, a plugin that lets you sign in to Payload CMS without a password by using a passkey. In this article, I cover the plugin’s features and setup process.

GitHub - Robot-Inventor/payload-passkey: Add passkey support to Payload CMS.

Add passkey support to Payload CMS. Contribute to Robot-Inventor/payload-passkey development by creating an account on GitHub.

github.com

Why I built it

Payload CMS is an excellent CMS, but its built-in authentication supports email addresses and passwords. If you want two-factor authentication or passkeys, you need a third-party plugin.

I had been using Payload TOTP, a plugin that adds TOTP-based two-factor authentication. After you enter your email address and password on the standard Payload CMS login screen, Payload TOTP takes you to another screen where you enter a one-time password.

Payload TOTP worked well for me, and I used it for some time. Over time, though, I grew tired of opening an authenticator app and entering a one-time password each time I logged in.

I started looking into passkeys. I could not find a Payload CMS plugin focused on passkeys, so Better Auth was the main option.

I had the following requirements:

• Keep Payload CMS’s existing authentication strategy for compatibility and visual consistency
• Work alongside Payload TOTP
• Use Payload CMS’s default authentication strategy for passwords, Payload TOTP for TOTP, and Better Auth for passkeys
• Allow login with either (email address AND password AND TOTP) OR a passkey

Several plugins let developers use Better Auth with Payload CMS, but none matched my use case:

• @delmaredigital/payload-better-auth: Replaces the entire login screen
• payload-auth: Had no documentation at the time
• payload-auth-plugin: Appeared to support passkeys as an experimental feature, but the relevant code was commented out, so the plugin did not support them

None of these plugins met my requirements.

I then found that @delmaredigital/payload-better-auth exports its Better Auth database adapter as a separate module. That gave me a way to wrap the adapter and build a plugin that met my requirements. I built payload-passkey around that approach.

payload-passkey features

With payload-passkey, you can add a passkey login button to Payload CMS’s default login screen and manage passkeys from the account management screen. The plugin includes the following features:

• A passkey login button on Payload CMS’s default login screen
• Passkey management from the account management screen
• Automatic token refresh when you enable it in Payload CMS
• Compatibility with Payload TOTP
• Passkey autofill support
• i18n support
• A design that uses Payload CMS UI components and fits into the dashboard

After you enable payload-passkey, you will see a passkey login button on the login screen, as shown below.

You will also see a section for managing passkeys on the account management screen.

How to use payload-passkey

First, install the package.

pnpm add payload-passkey

Next, set the BETTER_AUTH_SECRET environment variable to a random string with at least 32 characters.

1
BETTER_AUTH_SECRET=your-secret-key-longer-than-32-characters

Add payload-passkey as a plugin in payload.config.ts. Set userCollection to the slug of the collection that stores your user data. Set modelName to the value of userCollection with the trailing s removed.

1
import { buildConfig } from "payload";
2
import { payloadPasskey } from "payload-passkey";
3

4
const config = buildConfig({
5
    collections: [
6
        {
7
            slug: "users",
8
            auth: true,
9
            fields: [...],
10
        },
11
    ],
12
    plugins: [
13
        payloadPasskey({
14
            rpID: "your-domain.example.com",
15
            rpName: "Example App",
16
            origin: "https://your-domain.example.com",
17
            modelName: "user",
18
            userCollection: "users",
19
            baseURL: "https://your-domain.example.com",
20
            secret: process.env.BETTER_AUTH_SECRET,
21
            trustedOrigins: ["https://your-domain.example.com"],
22
            generateId: "serial",
23
            firstUserAdmin: true,
24
            enablePasskeyAutofill: true
25
        })
26
    ]
27
});
28

29
export default config;

If you want to use payload-passkey with Payload TOTP, configure the plugins as follows.

1
import { buildConfig } from "payload";
2
import { payloadPasskey } from "payload-passkey";
3

4
const config = buildConfig({
5
    collections: [
6
        {
7
            slug: "users",
8
            auth: true,
9
            fields: [...],
10
        },
11
    ],
12
    plugins: [
13
        payloadPasskey({
14
            enableTotpCompatibility: true,
15
            rpID: "your-domain.example.com",
16
            rpName: "Example App",
17
            origin: "https://your-domain.example.com",
18
            modelName: "user",
19
            userCollection: "users",
20
            baseURL: "https://your-domain.example.com",
21
            secret: process.env.BETTER_AUTH_SECRET,
22
            trustedOrigins: ["https://your-domain.example.com"],
23
            generateId: "serial",
24
            firstUserAdmin: true,
25
            enablePasskeyAutofill: true
26
        }),
27
        // `payloadTotp()` must be called after `payloadPasskey()`;
28
        // otherwise, the collection generated by payload-passkey won't be protected by Payload TOTP.
29
        payloadTotp({
30
            collection: "users",
31
            totp: {
32
                issuer: "Example App"
33
            }
34
        })
35
    ]
36
});
37

38
export default config;

Run the database migrations, and you can start using passkeys with Payload CMS.

npm run payload migrate:create
npm run payload migrate

Conclusion

I released payload-passkey so you can add passkey support while keeping Payload CMS’s default authentication strategy and compatibility with Payload TOTP.

You can find the source code on GitHub. If you find a bug, please open an issue or send a PR.

GitHub - Robot-Inventor/payload-passkey: Add passkey support to Payload CMS.

Add passkey support to Payload CMS. Contribute to Robot-Inventor/payload-passkey development by creating an account on GitHub.

github.com