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.
143 lines
5.2 KiB
Plaintext
143 lines
5.2 KiB
Plaintext
---
|
|
title: Globals Access Control
|
|
label: Globals
|
|
order: 30
|
|
desc: Global-level Access Control is specified within each Global's `access` property and allows you to define which users can read or update Globals.
|
|
keywords: globals, access control, permissions, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
Global Access Control is [Access Control](../access-control/overview) used to restrict access to [Global](../configuration/globals) Documents, as well as what they can and cannot see within the [Admin Panel](../admin/overview) as it relates to that Global.
|
|
|
|
To add Access Control to a Global, use the `access` property in your [Global Config](../configuration/globals):
|
|
|
|
```ts
|
|
import type { GlobalConfig } from 'payload';
|
|
|
|
export const GlobalWithAccessControl: GlobalConfig = {
|
|
// ...
|
|
access: { // highlight-line
|
|
// ...
|
|
},
|
|
}
|
|
```
|
|
|
|
## Config Options
|
|
|
|
Access Control is specific to the operation of the request.
|
|
|
|
To add Access Control to a [Global](../configuration/globals), use the `access` property in the [Global Config](../configuration/globals):
|
|
|
|
```ts
|
|
import { GlobalConfig } from 'payload'
|
|
|
|
const GlobalWithAccessControl: GlobalConfig = {
|
|
// ...
|
|
// highlight-start
|
|
access: {
|
|
read: ({ req: { user } }) => {...},
|
|
update: ({ req: { user } }) => {...},
|
|
|
|
// Version-enabled Globals only
|
|
readVersion: () => {...},
|
|
},
|
|
// highlight-end
|
|
}
|
|
|
|
export default Header
|
|
```
|
|
|
|
The following options are available:
|
|
|
|
| Function | Allows/Denies Access |
|
|
| ----------------------- | -------------------------------------- |
|
|
| **`read`** | Used in the `findOne` Global operation. [More details](#read). |
|
|
| **`update`** | Used in the `update` Global operation. [More details](#update). |
|
|
|
|
If a Global 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). |
|
|
|
|
### Read
|
|
|
|
Returns a boolean result or optionally a [query constraint](../queries/overview) which limits who can read this global based on its current properties.
|
|
|
|
To add read Access Control to a [Global](../configuration/globals), use the `read` property in the [Global Config](../configuration/globals):
|
|
|
|
```ts
|
|
import { GlobalConfig } from 'payload'
|
|
|
|
const Header: GlobalConfig = {
|
|
// ...
|
|
// highlight-start
|
|
read: {
|
|
read: ({ req: { user } }) => {
|
|
return Boolean(user)
|
|
},
|
|
}
|
|
// highlight-end
|
|
}
|
|
```
|
|
|
|
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`. |
|
|
|
|
### Update
|
|
|
|
Returns a boolean result or optionally a [query constraint](../queries/overview) which limits who can update this global based on its current properties.
|
|
|
|
To add update Access Control to a [Global](../configuration/globals), use the `access` property in the [Global Config](../configuration/globals):
|
|
|
|
```ts
|
|
import { GlobalConfig } from 'payload'
|
|
|
|
const Header: GlobalConfig = {
|
|
// ...
|
|
// highlight-start
|
|
access: {
|
|
update: ({ req: { user }, data }) => {
|
|
return Boolean(user)
|
|
},
|
|
}
|
|
// highlight-end
|
|
}
|
|
```
|
|
|
|
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`. |
|
|
| **`data`** | The data passed to update the global with. |
|
|
|
|
### Read Versions
|
|
|
|
If the Global 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 [Global Config](../configuration/globals):
|
|
|
|
```ts
|
|
import type { GlobalConfig } from 'payload'
|
|
|
|
export const GlobalWithVersionsAccess: GlobalConfig = {
|
|
// ...
|
|
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`. |
|