5e4e27460e
### What? This PR fixes numerous links across the docs, both internal docs links and external links. This PR also fixes some minor formatting issues in some places, as well as optically aligns the markdown tables in tables that had broken links. ### Why? To properly link readers to the correct location in the docs, and for better formatting and easier consumption. ### How? Changes to many `.mdx` files in the `docs` folder. Notes: - There are duplicative section id's in `docs/authentication/email.mdx`, I've fixed one such link, but have left it as is for now.
340 lines
12 KiB
Plaintext
340 lines
12 KiB
Plaintext
---
|
|
title: Collection Access Control
|
|
label: Collections
|
|
order: 20
|
|
desc: With Collection-level Access Control you can define which users can create, read, update or delete Collections.
|
|
keywords: collections, access control, permissions, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
Collection Access Control is [Access Control](../access-control/overview) used to restrict access to Documents within a [Collection](../getting-started/concepts#collections), as well as what they can and cannot see within the [Admin Panel](../admin/overview) as it relates to that Collection.
|
|
|
|
To add Access Control to a Collection, use the `access` property in your [Collection Config](../configuration/collections):
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload';
|
|
|
|
export const CollectionWithAccessControl: CollectionConfig = {
|
|
// ...
|
|
access: { // highlight-line
|
|
// ...
|
|
},
|
|
}
|
|
```
|
|
|
|
## Config Options
|
|
|
|
Access Control is specific to the operation of the request.
|
|
|
|
To add Access Control to a Collection, use the `access` property in your [Collection Config](../configuration/collections):
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload';
|
|
|
|
export const CollectionWithAccessControl: CollectionConfig = {
|
|
// ...
|
|
// highlight-start
|
|
access: {
|
|
create: () => {...},
|
|
read: () => {...},
|
|
update: () => {...},
|
|
delete: () => {...},
|
|
|
|
// Auth-enabled Collections only
|
|
admin: () => {...},
|
|
unlock: () => {...},
|
|
|
|
// Version-enabled Collections only
|
|
readVersions: () => {...},
|
|
},
|
|
// highlight-end
|
|
}
|
|
```
|
|
|
|
The following options are available:
|
|
|
|
| Function | Allows/Denies Access |
|
|
| ----------------------- | -------------------------------------------- |
|
|
| **`create`** | Used in the `create` operation. [More details](#create). |
|
|
| **`read`** | Used in the `find` and `findByID` operations. [More details](#read). |
|
|
| **`update`** | Used in the `update` operation. [More details](#update). |
|
|
| **`delete`** | Used in the `delete` operation. [More details](#delete). |
|
|
|
|
If a Collection supports [`Authentication`](../authentication/overview), the following additional options are available:
|
|
|
|
| Function | Allows/Denies Access |
|
|
| ----------------------- | -------------------------------------------------------------- |
|
|
| **`admin`** | Used to restrict access to the [Admin Panel](../admin/overview). [More details](#admin). |
|
|
| **`unlock`** | Used to restrict which users can access the `unlock` operation. [More details](#unlock). |
|
|
|
|
If a Collection supports [Versions](../versions/overview), the following additional options are available:
|
|
|
|
| Function | Allows/Denies Access |
|
|
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
|
|
| **`readVersions`** | Used to control who can read versions, and who can't. Will automatically restrict the Admin UI version viewing access. [More details](#read-versions). |
|
|
|
|
### Create
|
|
|
|
Returns a boolean which allows/denies access to the `create` request.
|
|
|
|
To add create Access Control to a Collection, use the `create` property in the [Collection Config](../configuration/collections):
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const CollectionWithCreateAccess: CollectionConfig = {
|
|
// ...
|
|
access: {
|
|
// highlight-start
|
|
create: ({ req: { user }, data }) => {
|
|
return Boolean(user)
|
|
},
|
|
// highlight-end
|
|
},
|
|
}
|
|
```
|
|
|
|
The following arguments are provided to the `create` function:
|
|
|
|
| Option | Description |
|
|
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
| **`req`** | The [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object containing the currently authenticated `user`. |
|
|
| **`data`** | The data passed to create the document with. |
|
|
|
|
### Read
|
|
|
|
Returns a boolean which allows/denies access to the `read` request.
|
|
|
|
To add read Access Control to a Collection, use the `read` property in the [Collection Config](../configuration/collections):
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const CollectionWithReadAccess: CollectionConfig = {
|
|
// ...
|
|
access: {
|
|
// highlight-start
|
|
read: ({ req: { user } }) => {
|
|
return Boolean(user)
|
|
},
|
|
// highlight-end
|
|
},
|
|
}
|
|
```
|
|
|
|
<Banner type="success">
|
|
**Tip:**
|
|
Return a [Query](../queries/overview) to limit the Documents to only those that match the constraint. This can be helpful to restrict users' access to specific Documents. [More details](../queries/overview).
|
|
</Banner>
|
|
|
|
As your application becomes more complex, you may want to define your function in a separate file and import them into your Collection Config:
|
|
|
|
```ts
|
|
import type { Access } from 'payload'
|
|
|
|
export const canReadPage: Access = ({ req: { user } }) => {
|
|
// Allow authenticated users
|
|
if (user) {
|
|
return true
|
|
}
|
|
|
|
// By returning a Query, guest users can read public Documents
|
|
// Note: this assumes you have a `isPublic` checkbox field on your Collection
|
|
return {
|
|
isPublic: {
|
|
equals: true,
|
|
},
|
|
}
|
|
}
|
|
```
|
|
|
|
The following arguments are provided to the `read` function:
|
|
|
|
| Option | Description |
|
|
| --------- | -------------------------------------------------------------------------- |
|
|
| **`req`** | The [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object containing the currently authenticated `user`. |
|
|
| **`id`** | `id` of document requested, if within `findByID`. |
|
|
|
|
### Update
|
|
|
|
Returns a boolean which allows/denies access to the `update` request.
|
|
|
|
To add update Access Control to a Collection, use the `update` property in the [Collection Config](../configuration/collections):
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const CollectionWithUpdateAccess: CollectionConfig = {
|
|
// ...
|
|
access: {
|
|
// highlight-start
|
|
update: ({ req: { user }}) => {
|
|
return Boolean(user)
|
|
},
|
|
// highlight-end
|
|
},
|
|
}
|
|
```
|
|
|
|
<Banner type="success">
|
|
**Tip:**
|
|
Return a [Query](../queries/overview) to limit the Documents to only those that match the constraint. This can be helpful to restrict users' access to specific Documents. [More details](../queries/overview).
|
|
</Banner>
|
|
|
|
As your application becomes more complex, you may want to define your function in a separate file and import them into your Collection Config:
|
|
|
|
```ts
|
|
import type { Access } from 'payload'
|
|
|
|
export const canUpdateUser: Access = ({ req: { user }, id }) => {
|
|
// Allow users with a role of 'admin'
|
|
if (user.roles && user.roles.some((role) => role === 'admin')) {
|
|
return true
|
|
}
|
|
|
|
// allow any other users to update only oneself
|
|
return user.id === id
|
|
}
|
|
```
|
|
|
|
The following arguments are provided to the `update` function:
|
|
|
|
| Option | Description |
|
|
| ---------- | -------------------------------------------------------------------------- |
|
|
| **`req`** | The [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object containing the currently authenticated `user`. |
|
|
| **`id`** | `id` of document requested to update. |
|
|
| **`data`** | The data passed to update the document with. |
|
|
|
|
### Delete
|
|
|
|
Similarly to the Update function, returns a boolean or a [query constraint](/docs/queries/overview) to limit which documents can be deleted by which users.
|
|
|
|
To add delete Access Control to a Collection, use the `delete` property in the [Collection Config](../configuration/collections):
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const CollectionWithDeleteAccess: CollectionConfig = {
|
|
// ...
|
|
access: {
|
|
// highlight-start
|
|
delete: ({ req: { user }}) => {
|
|
return Boolean(user)
|
|
},
|
|
// highlight-end
|
|
},
|
|
}
|
|
```
|
|
|
|
As your application becomes more complex, you may want to define your function in a separate file and import them into your Collection Config:
|
|
|
|
```ts
|
|
import type { Access } from 'payload'
|
|
|
|
export const canDeleteCustomer: Access = async ({ req, id }) => {
|
|
if (!id) {
|
|
// allow the admin UI to show controls to delete since it is indeterminate without the `id`
|
|
return true
|
|
}
|
|
|
|
// Query another Collection using the `id`
|
|
const result = await req.payload.find({
|
|
collection: 'contracts',
|
|
limit: 0,
|
|
depth: 0,
|
|
where: {
|
|
customer: { equals: id },
|
|
},
|
|
})
|
|
|
|
return result.totalDocs === 0
|
|
}
|
|
```
|
|
|
|
The following arguments are provided to the `delete` function:
|
|
|
|
| Option | Description |
|
|
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| **`req`** | The [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object with additional `user` property, which is the currently logged in user. |
|
|
| **`id`** | `id` of document requested to delete. |
|
|
|
|
### Admin
|
|
|
|
If the Collection is used to access the [Admin Panel](../admin/overview#the-admin-user-collection), the `Admin` Access Control function determines whether or not the currently logged in user can access the admin UI.
|
|
|
|
To add Admin Access Control to a Collection, use the `admin` property in the [Collection Config](../collections/overview):
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const CollectionWithAdminAccess: CollectionConfig = {
|
|
// ...
|
|
access: {
|
|
// highlight-start
|
|
admin: ({ req: { user }}) => {
|
|
return Boolean(user)
|
|
},
|
|
// highlight-end
|
|
},
|
|
}
|
|
```
|
|
|
|
The following arguments are provided to the `admin` function:
|
|
|
|
| Option | Description |
|
|
| --------- | -------------------------------------------------------------------------- |
|
|
| **`req`** | The [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object containing the currently authenticated `user`. |
|
|
|
|
### Unlock
|
|
|
|
Determines which users can [unlock](/docs/authentication/operations#unlock) other users who may be blocked from authenticating successfully due to [failing too many login attempts](/docs/authentication/overview#config-options).
|
|
|
|
To add Unlock Access Control to a Collection, use the `unlock` property in the [Collection Config](../configuration/collections):
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const CollectionWithUnlockAccess: CollectionConfig = {
|
|
// ...
|
|
access: {
|
|
// highlight-start
|
|
unlock: ({ req: { user }}) => {
|
|
return Boolean(user)
|
|
},
|
|
// highlight-end
|
|
},
|
|
}
|
|
```
|
|
|
|
The following arguments are provided to the `unlock` function:
|
|
|
|
| Option | Description |
|
|
| --------- | -------------------------------------------------------------------------- |
|
|
| **`req`** | The [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object containing the currently authenticated `user`. |
|
|
|
|
### Read Versions
|
|
|
|
If the Collection has [Versions](../versions/overview) enabled, the `readVersions` Access Control function determines whether or not the currently logged in user can access the version history of a Document.
|
|
|
|
To add Read Versions Access Control to a Collection, use the `readVersions` property in the [Collection Config](../configuration/collections):
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const CollectionWithVersionsAccess: CollectionConfig = {
|
|
// ...
|
|
access: {
|
|
// highlight-start
|
|
readVersions: ({ req: { user }}) => {
|
|
return Boolean(user)
|
|
},
|
|
// highlight-end
|
|
},
|
|
}
|
|
```
|
|
|
|
The following arguments are provided to the `readVersions` function:
|
|
|
|
| Option | Description |
|
|
| --------- | -------------------------------------------------------------------------- |
|
|
| **`req`** | The [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object containing the currently authenticated `user`. |
|