README.md

Authorization Plugin

This plugin enables you to define roles based on basic permissions per collection.
✨ Roles are assigned to users to control access and manage permissions efficiently. 🚀

https://github.com/user-attachments/assets/1326d41d-8747-4582-9288-5943ee8615be

Usage

With this plugin, you're in full control of user roles and permissions in Payload CMS. While there is a built-in Administrator role, you can go beyond that and create custom roles tailored to your needs.

Define roles with any combination of permissions—read, write, and publish—and apply them to any collection or global within your project.

How It Works

Each role you create consists of:
✅ Granular Permissions: Assign read, write, or publish permissions to collections and globals.
✅ Hierarchical Access:

• Write access automatically includes read access.
• Publish access includes both write and read access.

✅ Field-Level Permissions: Restrict a permission to specific fields within a collection. Leave the fields list empty to apply the permission to all fields.

With this powerful system, you have complete flexibility in managing access control—ensuring the right people have the right level of control.

Administrators can set as many permissions he/she wants within a role and as many as roles within a user

Field-Level Permissions

In addition to collection-level access control, you can now restrict permissions to specific fields within a collection.

When defining a permission in a role, you can optionally specify a list of field names. If provided, the permission applies only to those fields. If left empty, the permission applies to all fields (default behavior).

Example

A role with a read permission on articles restricted to the title and summary fields:

{
  entity: ['articles'],
  type: ['read'],
  fields: ['title', 'summary'],
}

Users with this role will be able to read the articles collection, but only the title and summary fields will be accessible — all other fields will be hidden.

Note: Field-level permissions are stored in the JWT so they are available at runtime without an extra database lookup.

Install

• Install the plugin using your node package manager, e.g:

pnpm add @shefing/authorization

Setup

In the payload.config.ts add the following:

plugins: [
    ...plugins,
    addAccess({
      rolesCollection: 'roles', // name of the collection defining the roles
      permissionsField: 'permissions', // name of the field within the role collection
      excludedCollections: ['posts', 'media'] // enable to exclude some collections from permission control
    }),

Install the roles collection (you don't have to use this collection, you can write your own roles).

  import { Roles } from '@shefing/authorization'
  collections: [...collection, Roles],

Fields Configuration

The users collection must be update to include the following fields:

      import {userFields} from '@shefing/authorization'

      fields:[
        ...fields,
        ...userFields,
      ]

isAdmin Role

When isAdmin is enabled, the user has full access to the system, including:

✅ Read, write, and publish across all collections and globals
✅ Manage all content without restrictions
✅ Access admin-only features

This role ensures complete control over the CMS, allowing seamless content management.

isGenerator Role

When isGenerator is enabled, the user can only generate static content without consuming dependencies in the API.

{
  name: 'belong',
  label: 'Belongs To',
  type: 'relationship',
  hasMany: true,
  relationTo: 'movies',
  index: true,
  access: {
    // Only non API users can read the field
    read: isNotGeneratorUserFieldLevel,
  }
},

Roadmap

See the consolidated ROADMAP.md at the repo root and the live RoadMap issues for Authorization.

P0

• Deny-list mode for field permissions (today only allow-list). Many teams want "all fields except internalNotes".
• Row-level / where-based permissions — permission entries carry a where clause merged into Payload's access functions.
• Role inheritance — extends: ['editor'].

P1

• Per-locale permissions for localized collections.
• Time-boxed permissions (validFrom / validUntil).
• Audit log of role/permission changes — surfaces nicely alongside authors-info.
• Admin UI matrix view — collections × roles × permissions, batch-edit.

P2

• Import/export roles as JSON for environment promotion.
• CLI helper: pnpm shefing-auth check <user> <collection>.