@composius/payload-plugin-auth

A Payload CMS plugin that turns a users collection into a role-based auth collection — configurable roles, sensible auth hardening, and exported access helpers (hasRole, hasRoleOrOwner) for use in your other collections.

If the collection already exists in your config it is extended (your explicit settings win); otherwise it is created.

Fields

| Field | Type | Notes | | ------ | -------- | ---------------------------------------------------------------- | | name | text | required, used as admin title | | role | select | required, saved to the JWT; only admins can set or change it |

Email and password are added by Payload's auth. The collection also sets:

• Cookies: secure in production only (plain-http localhost logins keep working in dev), sameSite: 'Lax'.
• Brute-force protection: 5 max login attempts, 15 minutes lock time.
• Admin UI: the collection is hidden from users without the admin role.
• Access: create/delete admin only, read any authenticated user, update admin or the user themselves.

Admin lockout protection

• The first user created is always given the admin role, whatever was submitted — otherwise the default role would apply (role changes are admin-only) and nobody could ever manage users.
• The last admin cannot be deleted or demoted; such operations fail with a 403.
• Duplicating a user resets its role to defaultRole rather than copying it. A duplicate copies field values straight off the source document, so without this an admin's role would ride onto the copy without passing the admin-only create access on the field (GHSA-vc4h-q48j-5hcx). Payload enforces field access on duplicate as of 3.90.0; the reset means the guarantee does not depend on that alone.
• adminRole/defaultRole values that are not in roles throw at config build time.

Requirements

The following dependencies are required to be installed in your project before using this plugin:

• payload (^3.90.1)

pnpm add payload

[!IMPORTANT] Upgrading to Payload 3.90.x needs a migration. 3.90.0 throttles the forgot-password flow so an unauthenticated caller can no longer hold an account in lockout (GHSA-v5gf-vpjc-pc7w), and it tracks that with a new resetPasswordRequestedAt field on auth collections. On a relational database (Postgres, SQLite) generate and run a migration after upgrading:

pnpm payload migrate:create
pnpm payload migrate

MongoDB needs no migration. This matters here because the plugin turns account lockout on by default (maxLoginAttempts: 5, lockTime 15 minutes), so every app using it was exposed until 3.90.0.

Usage

import { buildConfig } from 'payload'
import { ComposiusPayloadPluginAuth, hasRole, hasRoleOrOwner } from '@composius/payload-plugin-auth'

export default buildConfig({
  plugins: [
    ComposiusPayloadPluginAuth({
      // Custom roles: the role select offers these instead of the defaults
      roles: [
        { label: 'Admin', value: 'admin' },
        { label: 'Author', value: 'author' },
        { label: 'Member', value: 'member' },
      ],
      // New users become members; the very first user still becomes admin
      defaultRole: 'member',
    }),
  ],
  collections: [
    {
      slug: 'articles',
      access: {
        read: () => true,
        create: hasRole('admin', 'author'),
        // admins see everything, authors only the articles they authored
        update: hasRoleOrOwner(['admin'], 'author'),
        delete: hasRole('admin'),
      },
      fields: [{ name: 'author', type: 'relationship', relationTo: 'users' }],
    },
  ],
  // ...
})

Access helpers

• hasRole(...roles) — collection access allowing users whose role is one of the given values.
• hasRoleFieldLevel(...roles) — the same check as field-level access (field access cannot return a query).
• hasRoleOrOwner(roles, ownerField = 'id') — allows the given roles, and otherwise restricts the operation to documents whose ownerField equals the user's id. The default 'id' gives "self" access on the users collection; pass a relationship field name ('author', 'owner', …) for other collections.
• isAuthenticated — allows any authenticated user.
• isAdmin — allows only the plugin's adminRole (follows the option, default 'admin').
• isAdminOrHasRole(...roles) — allows the plugin's adminRole or any of the given roles.
• isAuthenticatedOrPublished — allows any authenticated user, and restricts the public to published documents (_status: 'published'); for collections with drafts enabled.
• hiddenUnlessAdmin — for admin.hidden on a collection or global: hides it from the admin nav and routes for everyone but the plugin's adminRole. Pass it by reference, like the access helpers.
• hiddenUnlessAdminOrHasRole(...roles) — the same, but also keeps the entity visible to the given roles.

{
  slug: 'settings',
  admin: {
    hidden: hiddenUnlessAdmin,
    // or: hidden: hiddenUnlessAdminOrHasRole('editor'),
  },
  // ...
}

Options

All optional — defaults shown as comments:

ComposiusPayloadPluginAuth({
  // Access per operation. Defaults: create/delete = admin role,
  // read = is authenticated, update = admin role or the user themselves.
  access: { read, create, update, delete },

  // Role value with full access to the users collection and admin UI.
  adminRole: 'admin',

  // Role value assigned to new users (except the very first, who becomes admin).
  defaultRole: 'viewer',

  // Selectable roles. Default: Admin, Editor, Viewer.
  roles: [
    { label: 'Admin', value: 'admin' },
    { label: 'Editor', value: 'editor' },
    { label: 'Viewer', value: 'viewer' },
  ],

  // Slug of the auth collection to extend or create.
  slug: 'users',

  // Keeps the collection schema but disables runtime behavior (default: false).
  disabled: false,
})

Development

From the monorepo root:

pnpm install
pnpm dev:auth                                        # dev Payload app with this plugin
pnpm vitest run packages/payload-plugin-auth/test    # unit tests
pnpm vitest run dev/configs/auth                     # integration tests
pnpm --filter @composius/payload-plugin-auth build  # build to dist/

See the root README for the release flow.