74 lines
3.8 KiB
Plaintext
74 lines
3.8 KiB
Plaintext
---
|
|
title: Authentication Config
|
|
label: Config
|
|
order: 20
|
|
---
|
|
|
|
Payload's Authentication is extremely powerful and gives you everything you need when you go to build a new app or site in a secure and responsible manner.
|
|
|
|
To enable Authentication on a collection, define an `auth` property and set it to either `true` or to an object containing the options below.
|
|
|
|
## Options
|
|
|
|
| Option | Description |
|
|
| ---------------------- | -------------|
|
|
| **`useAPIKey`** | Payload Authentication provides for API keys to be set on each user within an Authentication-enabled Collection. [More](/docs/authentication/config#api-keys) |
|
|
| **`tokenExpiration`** | How long (in seconds) to keep the user logged in. JWTs and HTTP-only cookies will both expire at the same time. |
|
|
| **`maxLoginAttempts`** | Only allow a user to attempt logging in X amount of times. Automatically locks out a user from authenticating if this limit is passed. Set to `0` to disable. |
|
|
| **`lockTime`** | Set the time that a user should be locked out if they fail authentication more times than `maxLoginAttempts` allows for. |
|
|
| **`depth`** | How many levels deep a `user` document should be populated when creating the JWT and binding the `user` to the express `req`. Defaults to `0` and should only be modified if absolutely necessary, as this will affect performance. |
|
|
| **`cookies`** | Set cookie options, including `secure`, `sameSite`, and `domain`. For advanced users. |
|
|
| **`forgotPassword`** | Customize the way that the `forgotPassword` operation functions. [More](/docs/authentication/config#forgot-password) |
|
|
| **`verify`** | Set to `true` or pass an object with verification options to require users to verify by email before they are allowed to log into your app. [More](/docs/authentication/config#email-verification) |
|
|
|
|
### API keys
|
|
|
|
To integrate with third-party APIs or services, you might need the ability to generate API keys that can be used to identify as a certain user within Payload.
|
|
|
|
For example, if you have a third-party service or external app that needs to be able to perform protected actions at its discretion, you have two options:
|
|
|
|
1. Create a user for the third-party app, and log in each time to receive a token before you attempt to access any protected actions
|
|
1. Enable API key support for the Collection, where you can generate a non-expiring API key per user in the collection
|
|
|
|
Technically, both of these options will work for third-party integrations but the second option with API key is simpler, because it reduces the amount of work that your integrations need to do to be authenticated properly.
|
|
|
|
To enable API keys on a collection, set the `useAPIKey` auth option to `true`. From there, a new interface will appear in the Admin panel for each document within the collection that allows you to generate an API key for each user in the Collection.
|
|
|
|
##### Authenticating via API Key
|
|
|
|
To utilize your API key while interacting with the REST or GraphQL API, add the `Authorization` header.
|
|
|
|
**For example, using Fetch:**
|
|
```js
|
|
const response = await fetch('http://localhost:3000/api/pages', {
|
|
headers: {
|
|
Authorization: `${collection.labels.singular} API-Key ${YOUR_API_KEY}`,
|
|
},
|
|
});
|
|
```
|
|
|
|
### Forgot Password
|
|
|
|
You can customize how the Forgot Password workflow operates with the following options on the `auth.forgotPassword` property:
|
|
|
|
**`generateEmailHTML`**
|
|
|
|
Function that accepts one argument, containing `{ req, token, user }`, that allows for overriding the HTML within emails that are sent to users attempting to reset their password. The function should return a string that supports HTML, which can be a full HTML email.
|
|
|
|
Example:
|
|
|
|
```js
|
|
{
|
|
slug: 'customers',
|
|
auth: {
|
|
forgotPassword: {
|
|
generateEmailHTML: ({ req, token, user }) => {
|
|
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
|