207 lines
9.6 KiB
Plaintext
207 lines
9.6 KiB
Plaintext
---
|
|
title: Authentication Config
|
|
label: Config
|
|
order: 20
|
|
desc: Enable and customize options in the Authentication config for features including Forgot Password, Login Attempts, API key usage and more.
|
|
keywords: authentication, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
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 (in milliseconds) 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 `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) |
|
|
| **`disableLocalStrategy`** | Advanced - disable Payload's built-in local auth strategy. Only use this property if you have replaced Payload's auth mechanisms with your own. |
|
|
| **`strategies`** | Advanced - an array of custom authentification strategies to extend this collection's authentication with. [More](/docs/authentication/custom-strategies) |
|
|
|
|
### 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.
|
|
|
|
<Banner type="success">
|
|
<strong>Tip:</strong>
|
|
<br />
|
|
HTML templating can be used to create custom email templates, inline CSS automatically, and more.
|
|
You can make a reusable function that standardizes all email sent from Payload, which makes
|
|
sending custom emails more DRY. Payload doesn't ship with an HTML templating engine, so you are
|
|
free to choose your own.
|
|
</Banner>
|
|
|
|
Example:
|
|
|
|
```ts
|
|
import { CollectionConfig } from 'payload'
|
|
|
|
export const Customers: CollectionConfig = {
|
|
slug: 'customers',
|
|
auth: {
|
|
forgotPassword: {
|
|
// highlight-start
|
|
generateEmailHTML: ({ req, token, user }) => {
|
|
// Use the token provided to allow your user to reset their password
|
|
const resetPasswordURL = `https://yourfrontend.com/reset-password?token=${token}`
|
|
|
|
return `
|
|
<!doctype html>
|
|
<html>
|
|
<body>
|
|
<h1>Here is my custom email template!</h1>
|
|
<p>Hello, ${user.email}!</p>
|
|
<p>Click below to reset your password.</p>
|
|
<p>
|
|
<a href="${resetPasswordURL}">${resetPasswordURL}</a>
|
|
</p>
|
|
</body>
|
|
</html>
|
|
`
|
|
},
|
|
// highlight-end
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
<Banner type="warning">
|
|
<strong>Important:</strong>
|
|
<br />
|
|
If you specify a different URL to send your users to for resetting their password, such as a page
|
|
on the frontend of your app or similar, you need to handle making the call to the Payload REST or
|
|
GraphQL reset-password operation yourself on your frontend, using the token that was provided for
|
|
you. Above, it was passed via query parameter.
|
|
</Banner>
|
|
|
|
**`generateEmailSubject`**
|
|
|
|
Similarly to the above `generateEmailHTML`, you can also customize the subject of the email. The function argument are the same but you can only return a string - not HTML.
|
|
|
|
Example:
|
|
|
|
```ts
|
|
{
|
|
slug: 'customers',
|
|
auth: {
|
|
forgotPassword: {
|
|
// highlight-start
|
|
generateEmailSubject: ({ req, user }) => {
|
|
return `Hey ${user.email}, reset your password!`;
|
|
}
|
|
// highlight-end
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Email Verification
|
|
|
|
If you'd like to require email verification before a user can successfully log in, you can enable it by passing `true` or an `options` object to `auth.verify`. The following options are available:
|
|
|
|
**`generateEmailHTML`**
|
|
|
|
Function that accepts one argument, containing `{ req, token, user }`, that allows for overriding the HTML within emails that are sent to users indicating how to validate their account. The function should return a string that supports HTML, which can optionally be a full HTML email.
|
|
|
|
Example:
|
|
|
|
```ts
|
|
import { CollectionConfig } from 'payload'
|
|
|
|
export const Customers: CollectionConfig = {
|
|
slug: 'customers',
|
|
auth: {
|
|
verify: {
|
|
// highlight-start
|
|
generateEmailHTML: ({ req, token, user }) => {
|
|
// Use the token provided to allow your user to verify their account
|
|
const url = `https://yourfrontend.com/verify?token=${token}`
|
|
|
|
return `Hey ${user.email}, verify your email by clicking here: ${url}`
|
|
},
|
|
// highlight-end
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
<Banner type="warning">
|
|
<strong>Important:</strong>
|
|
<br />
|
|
If you specify a different URL to send your users to for email verification, such as a page on the
|
|
frontend of your app or similar, you need to handle making the call to the Payload REST or GraphQL
|
|
verification operation yourself on your frontend, using the token that was provided for you.
|
|
Above, it was passed via query parameter.
|
|
</Banner>
|
|
|
|
**`generateEmailSubject`**
|
|
|
|
Similarly to the above `generateEmailHTML`, you can also customize the subject of the email. The function argument are the same but you can only return a string - not HTML.
|
|
|
|
Example:
|
|
|
|
```ts
|
|
{
|
|
slug: 'customers',
|
|
auth: {
|
|
forgotPassword: {
|
|
// highlight-start
|
|
generateEmailSubject: ({ req, user }) => {
|
|
return `Hey ${user.email}, reset your password!`;
|
|
}
|
|
// highlight-end
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Admin autologin
|
|
|
|
For testing and demo purposes you may want to skip forcing the admin user to login in order to access the panel.
|
|
The `admin.autologin` property is used to configure the how visitors are handled when accessing the Admin Panel.
|
|
The default is that all users will have to login and this should not be enabled for environments where data needs to protected.
|
|
|
|
#### autoLogin Options
|
|
|
|
| Option | Description |
|
|
| ----------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
| **`email`** | The email address of the user to login as |
|
|
| **`password`** | The password of the user to login as |
|
|
| **`prefillOnly`** | If set to true, the login credentials will be prefilled but the user will still need to click the login button. |
|
|
|
|
The recommended way to use this feature is behind an environment variable to ensure it is disabled when in production.
|
|
|
|
**Example:**
|
|
|
|
```ts
|
|
export default buildConfig({
|
|
admin: {
|
|
user: 'users',
|
|
// highlight-start
|
|
autoLogin:
|
|
process.env.PAYLOAD_PUBLIC_ENABLE_AUTOLOGIN === 'true'
|
|
? {
|
|
email: 'test@example.com',
|
|
password: 'test',
|
|
prefillOnly: true,
|
|
}
|
|
: false,
|
|
// highlight-end
|
|
},
|
|
collections: [
|
|
/** */
|
|
],
|
|
})
|
|
```
|