tabshift/payloadcms
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: adds examples and descriptions to access control

Browse Source
This commit is contained in:
James
2021-01-04 21:19:19 -05:00
parent 6ee2a762e8
commit cab10e2028
5 changed files with 170 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
docs/Access-Control/collections.mdx
View File

@@ -4,29 +4,37 @@ label: Collections
order: 20
---
Collections access control is specified with functions inside a collection config.
You can define Collection-level Access Control within each Collection's `access` property.
## Available Functions
## Available Controls
| Function | Allows/Denies Access |
| ---------- | ----------------------------------------- |
| **create** | creating a collection document |
| **read** | reading a collection document |
| **update** | updating a collection document |
| **delete** | deleting a collection document |
| **admin** | viewing collection in the admin interface |
| Function | Allows/Denies Access |
| ------------------------ | -------------------- |
| **[`create`](#create)** | Used in the `create` operation |
| **[`read`](#read)** | Used in the `find` and `findByID` operations |
| **[`update`](#update)** | Used in the `update` operation |
| **[`delete`](#delete)** | Used in the `delete` operation |
#### Auth-enabled Controls
If a Collection supports [`Authentication`](/docs/authentication/overview), the following Access Controls become available:
| Function | Allows/Denies Access |
| ----------------------- | -------------------- |
| **[`admin`](#admin)** | Used to restrict access to the Payload Admin panel |
| **[`unlock`](#unlock)** | Used to restrict which users can access the `unlock` operation |
**Example Collection config:**
```js
// Collection config
module.exports = {
slug: "public-user",
export default {
slug: "posts",
// highlight-start
access: {
create: () => true,
read: () => true,
update: () => true,
delete: () => true,
admin: () => true,
create: ({ req: { user } }) => { ... },
read: ({ req: { user } }) => { ... },
update: ({ req: { user } }) => { ... },
delete: ({ req: { user } }) => { ... },
admin: ({ req: { user } }) => { ... },
},
// highlight-end
};
@@ -34,62 +42,63 @@ module.exports = {
### Create
Create access functions return a boolean result which allows/denies access to create a document
Returns a boolean which allows/denies access to the `create` request.
#### Arguments
**Available arguments:**
The function receives one `args` argument that contains the following properties:
| Option | Description |
| --------- | --------------------------------------------------------------------------------------------------- |
| **`req`** | The Express `request` object with additional `user` property, which is the currently logged in user |
| Option | Description |
| --------- | ----------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
### Read
Read access functions can return a boolean result or optionally return a [where constraint](/docs/queries/overview).
Read access functions can return a boolean result or optionally return a [query constraint](/docs/queries/overview) which limits the documents that are returned to only those that match the constraint you provide. This can be helpful to restrict users' access to only certain documents however you specify.
#### Arguments
**Available arguments:**
The function receives one `args` argument that contains the following properties:
| Option | Description |
| --------- | --------------------------------------------------------------------------------------------------- |
| **`req`** | The Express `request` object with additional `user` property, which is the currently logged in user |
| **`id`** | `id` of document requested. Value is `undefined` if not querying for specific ID |
| Option | Description |
| --------- | ----------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
| **`id`** | `id` of document requested, if within `findByID`. Otherwise, `id` is undefined. |
### Update
Update access functions can return a boolean result or optionally return a [where constraint](/docs/queries/overview).
Update access functions can return a boolean result or optionally return a [query constraint](/docs/queries/overview) to limit the document(s) that can be updated by the currently authenticated user. For example, returning a `query` from the `update` Access Control is helpful in cases where you would like to restrict a user to only being able to update the documents containing a `createdBy` relationship field equal to the user's ID.
#### Arguments
**Available arguments:**
The function receives one `args` argument that contains the following properties:
| Option | Description |
| --------- | --------------------------------------------------------------------------------------------------- |
| **`req`** | The Express `request` object with additional `user` property, which is the currently logged in user |
| Option | Description |
| --------- | ----------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
| **`id`** | `id` of document requested to update |
### Delete
Delete access functions can return a boolean result or optionally return a [where constraint](/docs/queries/overview).
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.
#### Arguments
**Available arguments:**
The function receives one `args` argument that contains the following properties:
| Option | Description |
| --------- | --------------------------------------------------------------------------------------------------- |
| Option | Description |
| --------- | ----------- |
| **`req`** | The Express `request` object with additional `user` property, which is the currently logged in user |
| **`id`** | `id` of the document being deleted |
| **`id`** | `id` of document requested to delete |
### Admin
Admin access functions determine whether or not a user can access the admin UI.
If the Collection is [used to access the Payload Admin panel](/docs/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.
** Only applicable on collections that have auth **
**Available arguments:**
It receives one `args` argument that contains the following properties:
| Option | Description |
| --------- | ----------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
| Option | Description |
| --------- | --------------------------------------------------------------------------------------------------- |
| **`req`** | The Express `request` object with additional `user` property, which is the currently logged in 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/config#options).
**Available arguments:**
| Option | Description |
| --------- | ----------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |

70
docs/Access-Control/fields.mdx
View File

@@ -4,30 +4,30 @@ label: Fields
order: 30
---
Field access control is specified with functions inside a field's config. The functions return a boolean value to allow or deny access for the specified operation.
Field Access Control is specified with functions inside a field's config. All field-level Controls return a boolean value to allow or deny access for the specified operation. No field-level Access Controls support returning query constraints.
## Available Functions
## Available Controls
| Function | Allows/Denies Access |
| ---------- | --------------------------------------- |
| **create** | setting a field's value on new document |
| **read** | reading a field's value |
| **update** | updating a field's value |
| Function | Purpose |
| ------------------------ | ------- |
| **[`create`](#create)** | Allows or denies the ability to set a field's value when creating a new document |
| **[`read`](#read)** | Allows or denies the ability to read a field's value |
| **[`update`](#update)** | Allows or denies the ability to update a field's value |
**Example Collection config:**
```js
// Collection config
module.exports = {
slug: 'public-user',
export default {
slug: 'posts',
fields: [
{
name: 'lockedDownField',
label: 'Locked Down',
name: 'title',
label: 'Title',
type: 'text'
// highlight-start
access: {
create: () => true,
read: () => true,
update: () => true,
create: ({ req: { user } }) => { ... },
read: ({ req: { user } }) => { ... },
update: ({ req: { user } }) => { ... },
},
// highlight-end
};
@@ -37,38 +37,32 @@ module.exports = {
### Create
Create access functions return a boolean result which allows or denies the ability to set a field's value when creating a new document
Returns a boolean which allows or denies the ability to set a field's value when creating a new document. If `false` is returned, any passed values will be discarded.
#### Arguments
**Available arguments:**
The function receives one `args` argument that contains the following properties:
| Option | Description |
| --------- | --------------------------------------------------------------------------------------------------- |
| **`req`** | The Express `request` object with additional `user` property, which is the currently logged in user |
| Option | Description |
| --------- | ----------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
### Read
Read access functions return a boolean result which allows or denies the ability to read a field's value
Returns a boolean which allows or denies the ability to read a field's value. If `false`, the entire property is omitted from the resulting document.
#### Arguments
**Available arguments:**
The function receives one `args` argument that contains the following properties:
| Option | Description |
| --------- | --------------------------------------------------------------------------------------------------- |
| **`req`** | The Express `request` object with additional `user` property, which is the currently logged in user |
| **`id`** | `id` of the document being read |
| Option | Description |
| --------- | ----------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
| **`id`** | `id` of the document being read |
### Update
Update access functions return a boolean result which allows or denies the ability to update a field's value
Returns a boolean which allows or denies the ability to update a field's value. If `false` is returned, any passed values will be discarded.
#### Arguments
**Available arguments:**
The function receives one `args` argument that contains the following properties:
| Option | Description |
| --------- | --------------------------------------------------------------------------------------------------- |
| **`req`** | The Express `request` object with additional `user` property, which is the currently logged in user |
| **`id`** | `id` of the document being updated |
| Option | Description |
| --------- | ----------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
| **`id`** | `id` of the document being updated |

46
docs/Access-Control/globals.mdx
View File

@@ -4,23 +4,23 @@ label: Globals
order: 40
---
Globals access control is specified with functions inside a globals config. The functions return a boolean value to allow or deny access for the specified operation.
You can define Global-level Access Control within each Global's `access` property.
## Available Functions
## Available Controls
| Function | Allows/Denies Access |
| ---------- | -------------------------- |
| **read** | reading a global document |
| **update** | updating a global document |
| Function | Allows/Denies Access |
| ------------------------ | -------------------- |
| **[`read`](#read)** | Used in the `findOne` Global operation |
| **[`update`](#update)** | Used in the `update` Global operation |
**Example Global config:**
```js
// Collection config
module.exports = {
slug: "public-user",
export default {
slug: "header",
// highlight-start
access: {
read: () => true,
update: () => true,
read: ({ req: { user } }) => { ... },
update: ({ req: { user } }) => { ... },
},
// highlight-end
};
@@ -28,24 +28,20 @@ module.exports = {
### Read
A read access function allows or denies the ability to read a global. The function must return a boolean result.
Returns a boolean result to allow or deny a user's ability to read the Global.
#### Arguments
**Available arguments:**
The function receives one `args` argument that contains the following properties:
| Option | Description |
| --------- | --------------------------------------------------------------------------------------------------- |
| **`req`** | The Express `request` object with additional `user` property, which is the currently logged in user |
| Option | Description |
| --------- | ----------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |
### Update
An update access function allows or denies the ability to update a global. The function must return a boolean result.
Returns a boolean result to allow or deny a user's ability to update the Global.
#### Arguments
**Available arguments:**
The function receives one `args` argument that contains the following properties:
| Option | Description |
| --------- | --------------------------------------------------------------------------------------------------- |
| **`req`** | The Express `request` object with additional `user` property, which is the currently logged in user |
| Option | Description |
| --------- | ----------- |
| **`req`** | The Express `request` object containing the currently authenticated `user` |

51
docs/Access-Control/overview.mdx
View File

@@ -4,33 +4,40 @@ label: Overview
order: 10
---
Access can be configured at a Collection-level or field-level within your Collection configuration.
Access control within Payload is extremely powerful while remaining easy and intuitive to manage. Declaring who should have access to what documents is no more complex than writing a simple JavaScript function that either returns a `boolean` or a [`query`](/docs/queries/overview) constraint to restrict which documents users can interact with.
Access control functions return a boolean result in most cases. Certain functions also support returning a [where constraint object](/docs/queries/overview)
**Example use cases:**
**Default access control requires a logged in user to do anything.**
- Allowing anyone `read` access to all `Post`s
- Only allowing public access to `Post`s where a `status` field is equal to `published`
- Giving only `User`s with a `role` field equal to `admin` the ability to delete `Page`(s)
- Allowing anyone to create `ContactSubmission`s, but only logged in users to `read`, `update` or `delete` them
- Restricting a `User` to only be able to see their own `Order`(s), but no others
- Allowing `User`s that belong to a certain `Organization` to access only that `Organization`'s `Resource`s
Local API skips access control by default, but can be enabled if you pass a user to the operation.
### Default Settings
## Access Control Types
**By default, all Collections and Globals require that a user is logged in to be able to interact in any way.** The default Access Control function evaluates the `user` from the Express `req` and returns `true` if a user is logged in, and `false` if not.
**Default Access function:**
```js
const defaultPayloadAccess = ({ req: { user } }) => {
// Return `true` if a user is found
// and `false` if it is undefined or null
return Boolean(user);
}
```
<Banner type="success">
<strong>Note:</strong><br/>
In the Local API, all Access Control functions are skipped by default, allowing your server to do whatever it needs. But, you can opt back in by setting the option <strong>overrideAccess</strong> to <strong>true</strong>.
</Banner>
### Access Control Types
You can manage access within Payload on three different levels:
- [Collections](/docs/access-control/collections)
- [Fields](/docs/access-control/fields)
- [Globals](/docs/access-control/globals)
### Collections
Talk about collection-level access control here.
### Globals
Talk about global access control here.
### Fields
Talk about field-level access control here.
### Admin
Talk about how to restrict collections' access to the Admin panel here.

41
docs/getting-started/concepts.mdx
View File

@@ -50,6 +50,16 @@ Hooks are an extremely powerful concept and are central to extending and customi
There are many more potential reasons to use Hooks. For more, visit the [Hooks documentation](/docs/hooks/overview).
### Access Control
<Banner type="info">
Access Control refers to Payload's system of defining who can do what to your API.
</Banner>
Access Control is extremely powerful but easy and intuitive to manage. You can easily define your own full-blown RBAC (role-based access control) or any other access control pattern that your scenario requires. No conventions or structure is forced on you whatsoever.
For more, visit the [Access Control documentation](/docs/access-control/overview).
### Depth
<Banner type="info">
@@ -115,12 +125,13 @@ If you were to query the Posts endpoint at, say, `http://localhost:3000/api/post
// ?depth=1
{
title: 'This post sucks',
author: {
id: '5f7dd05cd50d4005f8bcab17',
email: 'spiderman@superheroes.gov',
department: '5e3ca05cd50d4005f8bdab15'
}
id: '5ae8f9bde69e394e717c8832',
title: 'This post sucks',
author: {
id: '5f7dd05cd50d4005f8bcab17',
email: 'spiderman@superheroes.gov',
department: '5e3ca05cd50d4005f8bdab15'
}
}
```
@@ -132,13 +143,15 @@ To populate `user.author.department` in it's entirety you could specify `?depth=
// ?depth=2
{
title: 'This post sucks',
author: {
id: '5f7dd05cd50d4005f8bcab17',
email: 'spiderman@superheroes.gov',
department: {
name: 'Marvel'
}
}
id: '5ae8f9bde69e394e717c8832',
title: 'This post sucks',
author: {
id: '5f7dd05cd50d4005f8bcab17',
email: 'spiderman@superheroes.gov',
department: {
id: '5e3ca05cd50d4005f8bdab15',
name: 'Marvel'
}
}
}
```