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:
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:
The following options are available:
| Option | Description |
|---|---|
cookies | Set cookie options, including secure, sameSite, and domain. For advanced users. |
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. |
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. |
forgotPassword | Customize the way that the forgotPassword operation functions. More details. |
lockTime | Set the time (in milliseconds) that a user should be locked out if they fail authentication more times than maxLoginAttempts allows for. |
loginWithUsername | Ability to allow users to login with username/password. More |
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. |
removeTokenFromResponses | Set to true if you want to remove the token from the returned authentication API responses such as login or refresh. |
strategies | Advanced - an array of custom authentication strategies to extend this collection's authentication with. More details. |
tokenExpiration | How long (in seconds) to keep the user logged in. JWTs and HTTP-only cookies will both expire at the same time. |
useAPIKey | Payload Authentication provides for API keys to be set on each user within an Authentication-enabled Collection. More details. |
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 details. |
Login With Username
You can allow users to login with their username instead of their email address by setting the loginWithUsername property to true.
Example:
Or, you can pass an object with additional options:
allowEmailLogin
If set to true, users can log in with either their username or email address. If set to false, users can only log in with their username.
requireEmail
If set to true, an email address is required when creating a new user. If set to false, email is not required upon creation.
Auto-Login
For testing and demo purposes you may want to skip forcing the user to login in order to access your application. Typically, all users should be required to login, however, you can speed up local development time by enabling auto-login.
To enable auto-login, set the autoLogin property in the Admin Config:
The following options are available:
| Option | Description |
|---|---|
username | The username of the user to login as |
email | The email address of the user to login as |
password | The password of the user to login as. This is only needed if prefillOnly is set to true |
prefillOnly | If 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.