Made withPayload CMSTutorial

Overview of Payload CMS Access Control

P

Payload

Creator on the Payload CMS channel

Watch on YouTube ↗

29K viewsOct 11, 202217:33 runtime

Explore the power of Payload CMS's code-based access control, which transforms it from a headless CMS into a robust application framework. This overview demonstrates how to implement granular, role-based permissions, including multi-tenant setups where users only see content for…

Chapters

#payloadcms#tutorial#cmscrm

Core Concepts of Payload Access Control

Payload's access control is a powerful, code-based system that elevates it beyond a typical headless CMS to an application framework. Instead of being stored in a database, permissions are defined as functions within your codebase.

Granular Control: Define who can create, read, update, and delete documents on a per-collection and per-field basis.
Dynamic Admin UI: The Payload admin panel automatically adapts to the access control rules. Fields may become read-only, and collections or documents may be hidden entirely depending on the logged-in user's permissions.

Tip
Because access control is just code, it can be version-controlled with Git, is highly reusable, and can be as simple or complex as your application requires.

Implementing Role-Based Access Control (RBAC)

A common pattern is to implement RBAC using a roles field on the Users collection.

Add a roles field: Create a select field on your Users collection with hasMany: true to allow for multiple roles (e.g., admin, editor).
Save roles to JWT: Set saveToJWT: true on the roles field so the user's roles are available on every authenticated request via req.user.

Create Helper Functions: Write simple, reusable functions to check for roles.

// Example: /access/isAdmin.ts
import { Access } from 'payload/types';

export const isAdmin: Access = ({ req: { user } }) => {
  // Return true or false based on if the user has an admin role
  return Boolean(user?.roles?.includes('admin'));
};

Function-Based Access Control Examples

Access control functions can return a boolean or a query constraint.

Simple Boolean Access: return true to grant access or return false to deny it. This is ideal for straightforward checks like isAdmin.
Query Constraints: For read and update operations, returning a query constraint filters the set of documents a user can access. This is the foundation of ownership and multi-tenant rules.
```
// Example: Only allow users to see their own document
const isSelf: Access = ({ req: { user } }) => {
  if (user) {
    return { id: { equals: user.id } };
  }
  return false;
}
```
Field-Level Access: Apply access control directly to a specific field to restrict who can read or update it. This is useful for preventing non-admins from escalating their own privileges.
```
// In a collection config
fields: [
  {
    name: 'roles',
    type: 'select',
    access: {
      update: isAdmin // Only admins can change a user's roles
    }
  }
]
```

Building a Multi-Tenant System

You can restrict content access based on a site or tenant relationship.

Data Model: Add a relationship from Users to a Sites collection. This assigns users to one or more sites.
Content Filtering: In other collections (like Pages or Media), add a relationship to Sites.

Access Control Logic: Use a query constraint to filter content based on the user's assigned sites.

// Example: Only show pages for the user's sites
const hasSiteAccess: Access = ({ req: { user } }) => {
  if (user.roles.includes('admin')) return true;

  return {
    site: {
      in: user.sites // Assumes user.sites is an array of site IDs
    }
  };
}

Public vs. Private Content

Access control can also differentiate between authenticated and public users.

Important
If an access function receives a user object, the request is authenticated. If user is undefined, the request is from a public, unauthenticated user.

This allows you to implement logic where anyone can see published documents, but only authenticated users can see drafts.

// In an access function
if (!user) {
  // For public users, only return published documents
  return { _status: { equals: 'published' } };
}

Allowing Public Form Submissions

To create a public-facing form (like a contact request), you can open up create access for a collection while keeping other operations secure.

// On a 'Contact Requests' collection
access: {
  create: () => true, // Anyone can create a request
  read: isAdmin,      // Only admins can read them
  update: () => false,  // Nobody can ever update them
  delete: () => false  // Nobody can ever delete them
}