8952662db9
### What? This PR fixes many links in the docs as well as a few formatting and grammar issues. ### Why? To properly link users to the correct destination in the docs and present well-formatted docs. ### How? Changes to a few files in `docs/`
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](../configuration/collections):
|
|
|
|
```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`. |
|