Authentication Overview

Authentication is a critical part of any application. Payload provides a secure, portable way to manage user accounts out of the box. Payload Authentication is designed to be used in both the Admin Panel, all well as your own external applications, completely eliminating the need for paid, third-party platforms and services.

Here are some common use cases of Authentication in your own applications:

  • Customer accounts for an e-commerce app
  • User accounts for a SaaS product
  • P2P apps or social sites where users need to log in and manage their profiles
  • Online games where players need to track their progress over time

When Authentication is enabled on a Collection, Payload injects all necessary functionality to support the entire user flow. This includes all auth-related operations like account creation, logging in and out, and resetting passwords, all auth-related emails like email verification and password reset, as well as any necessary UI to manage users from the Admin Panel.

To enable Authentication on a Collection, use the auth property in the Collection Config:

1
import { CollectionConfig } from 'payload'
2
3
export const Users: CollectionConfig = {
4
// ...
5
auth: true,
6
}

Authentication Admin Panel functionality Admin Panel screenshot depicting an Admins Collection with Auth enabled

Config Options

Any Collection can opt-in to supporting Authentication. Once enabled, each Document that is created within the Collection can be thought of as a "user". This enables a complete authentication workflow on your Collection, such as logging in and out, resetting their password, and more.

To enable Authentication on a Collection, use the auth property in the Collection Config:

1
import { CollectionConfig } from 'payload'
2
3
export const Admins: CollectionConfig = {
4
// ...
5
auth: {
6
tokenExpiration: 7200, // How many seconds to keep the user logged in
7
verify: true, // Require email verification before being allowed to authenticate
8
maxLoginAttempts: 5, // Automatically lock a user out after X amount of failed logins
9
lockTime: 600 * 1000, // Time period to allow the max login attempts
10
// More options are available
11
},
12
}

The following options are available:

OptionDescription
cookiesSet cookie options, including secure, sameSite, and domain. For advanced users.
depthHow 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.
disableLocalStrategyAdvanced - disable Payload's built-in local auth strategy. Only use this property if you have replaced Payload's auth mechanisms with your own.
forgotPasswordCustomize the way that the forgotPassword operation functions. More details.
lockTimeSet the time (in milliseconds) that a user should be locked out if they fail authentication more times than maxLoginAttempts allows for.
maxLoginAttemptsOnly 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.
strategiesAdvanced - an array of custom authentification strategies to extend this collection's authentication with. More details.
tokenExpirationHow long (in seconds) to keep the user logged in. JWTs and HTTP-only cookies will both expire at the same time.
useAPIKeyPayload Authentication provides for API keys to be set on each user within an Authentication-enabled Collection. More details.
verifySet 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 details.

Admin Auto-Login

For testing and demo purposes you may want to skip forcing the admin user to login in order to access the Admin Panel. Typically, all users should be required to login to access the Admin Panel, however, you can speed up local development time by enabling auto-login.

To enable auto-login, set the autoLogin property in the Admin Config:

1
import { buildConfig } from 'payload/config'
2
3
export default buildConfig({
4
// ...
5
admin: {
6
// ...
7
autoLogin:
8
process.env.NEXT_PUBLIC_ENABLE_AUTOLOGIN === 'true'
9
? {
10
email: 'test@example.com',
11
password: 'test',
12
prefillOnly: true,
13
}
14
: false,
15
},
16
})

The following options are available:

OptionDescription
emailThe email address of the user to login as
passwordThe password of the user to login as
prefillOnlyIf set to true, the login credentials will be prefilled but the user will still need to click the login button.

Operations

All auth-related operations are available via Payload's REST, Local, and GraphQL APIs. These operations are automatically added to your Collection when you enable Authentication. More details.

Strategies

Out of the box Payload ships with a three powerful Authentication strategies:

Each of these strategies can work together or independently. You can also create your own custom strategies to fit your specific needs. More details.

HTTP-Only Cookies

HTTP-only cookies are a highly secure method of storing identifiable data on a user's device so that Payload can automatically recognize a returning user until their cookie expires. They are totally protected from common XSS attacks and cannot be read by JavaScript in the browser, unlike JWT's. More details.

JSON Web Tokens

JWT (JSON Web Tokens) can also be utilized to perform authentication. Tokens are generated on login, refresh and me operations and can be attached to future requests to authenticate users. More details.

API Keys

API Keys can be enabled on auth collections. These are particularly useful when you want to authenticate against Payload from a third party service. More details.

Custom Strategies

There are cases where these may not be enough for your application. Payload is extendable by design so you can wire up your own strategy when you need to. More details.

Next

Authentication Operations