Official Dynamic Database-Backed RBAC Plugin for Payload CMS

[Mhmod-Hsn]

Introduction

Hi Payload Team and Community! 👋

Following up on the work with audit logs, I’ve been working on another plugin to solve a very common architectural challenge in enterprise production environments: dynamic, database-backed Role-Based Access Control (RBAC).

While Payload provides excellent code-based access control, real-world applications often require administrators to create roles, define custom permissions, and assign them to users on the fly directly from the Admin UI, without redeploying code or modifying source files.

I’d love to share the plugin I built, gather feedback, and see if there is interest in listing it as a recommended community plugin or adapting parts of its architecture into the official Payload ecosystem!

---

The Plugin: payload-rbac-plugin

The goal of this plugin is to deliver a robust, database-backed RBAC system that is simple to configure, clean, and has zero database overhead during runtime access checks.

Core Features:

• Dynamic Collections: Automatically injects database-backed Roles and Permissions collections.
• Auth Collection Extension: Automatically injects a roles relationship field into your designated auth collection (e.g., users). This field is configured with saveToJWT: true, caching roles and permissions in the user's JWT to ensure runtime authorization checks require zero additional database queries.
• Bulk Permission Generator: To avoid creating permissions one by one, the Admin UI includes a Bulk CRUD Generator. You can select a collection slug (e.g., posts) and check CRUD operations to instantly generate separate permissions (e.g., posts:create, posts:read, posts:update, posts:delete) in one save.
• UI-Only Helper Fields: Bulk generator fields are purely for user convenience in the Admin panel and are never saved to the database, keeping database schemas clean and flat.
• Customizable Schemas: Allows developers to inject additional custom fields into both the Roles and Permissions schemas via rolesFields and permissionsFields options.
• Granular Panel Access: Supports hiding Roles and Permissions collections dynamically based on the current user's permissions, ensuring security for the RBAC panel itself.
• Helper Utilities: Provides clean utilities like checkPermission (an access control higher-order function) and hasPermission (a function to check a user's permissions manually).

---

Example Usage

1. Register the Plugin

Configure the plugin in your payload.config.ts:

import { buildConfig } from 'payload'
import { rbac, hasPermission } from 'payload-rbac-plugin'

export default buildConfig({
  collections: [
    {
      slug: 'posts',
      fields: [],
    },
  ],
  plugins: [
    rbac({
      enabled: true,
      authCollectionSlug: 'users',              // Default: 'users'
      rolesCollectionSlug: 'roles',              // Default: 'roles'
      permissionsCollectionSlug: 'permissions',   // Default: 'permissions'
      
      // Protect the RBAC control panels themselves using the dynamic helpers
      hidePermissions: ({ user }) => !hasPermission(user, 'access:permissions'),
      hideRoles: ({ user }) => !hasPermission(user, 'access:roles'),
    }),
  ],
})

2. Protect Collections (Access Control)

Apply standard Payload access control using the checkPermission helper:

import { checkPermission } from 'payload-rbac-plugin'

export const PostsCollection = {
  slug: 'posts',
  access: {
    create: checkPermission('posts:create'),
    read: checkPermission('posts:read'),
    update: checkPermission('posts:update'),
    delete: checkPermission('posts:delete'),
  },
  fields: [],
}

3. Verification in Custom Endpoints or Hooks

For custom routes, hooks, or conditional logic, verify permissions programmatically:

import { hasPermission } from 'payload-rbac-plugin'

const exportReportsEndpoint = (req, res) => {
  if (hasPermission(req.user, 'reports:export')) {
    // Proceed with report generation
  } else {
    res.status(403).send('Forbidden')
  }
}

---

Why this belongs in the Payload Ecosystem:

1. Decoupling Authorization Logic from Code: Defining permissions as simple strings (e.g., posts:create) and mapping them dynamically to roles database-side means you don't need to change your codebase or redeploy when user roles shift.
2. Standardized RBAC Pattern: It implements a battle-tested and clean database-backed RBAC implementation, providing a standard for community developers.
3. Zero-Overhead Access Checks: By caching user roles and their associated permissions directly in the JWT, checking permissions is a fast, CPU-only verification on the request object, avoiding slow database lookups on every request.

---

Links

• GitHub: https://github.com/Mhmod-Hsn/Payload-RBAC-Plugin
• NPM: https://www.npmjs.com/package/payload-rbac-plugin

I’d love to hear your thoughts and suggestions on this implementation!