Authentication is used within the Payload Admin panel itself as well as throughout your app(s) themselves however you determine necessary.
Admin panel screenshot depicting an Admins Collection with Auth enabled
Here are some common use cases of Authentication outside of Payload's dashboard itself:
By default, Payload provides you with a
User collection that supports Authentication, which is used to access the Admin panel. But, you can add support to one or many Collections of your own. For more information on how to customize, override, or remove the default
User collection, click here.
Every Payload Collection can opt-in to supporting Authentication by specifying the
auth property on the Collection's config to either
true or to an object containing
For a full list of all
auth options, click here.
Simple example collection:
By enabling Authentication on a config, the following modifications will automatically be made to your Collection:
hashfields will be added to your Collection's schema
operationswill be exposed via Payload's REST, Local, and GraphQL APIs
Once enabled, each document that is created within the Collection can be thought of as a
user - who can make use of commonly required authentication functions such as logging in / out, resetting their password, and more.
Click here for a list of all automatically-enabled Auth operations, including
refresh, and others.
Successfully logging in returns a
JWT (JSON web token) which is how a user will identify themselves to Payload. By providing this JWT via either an HTTP-only cookie or an
Authorization header, Payload will automatically identify the user and add its user JWT data to the Express
req, which is available throughout Payload including within access control, hooks, and more.
You can specify what data gets encoded to the JWT token by setting
saveToJWT to true in your auth collection fields. If you wish to use a different key other than the field
name, you can provide it to
saveToJWT as a string. It is also possible to use
saveToJWT on fields that are nested in inside groups and tabs. If a group has a
saveToJWT set it will include the object with all sub-fields in the token. You can set
saveToJWT: false for any fields you wish to omit. If a field inside a group has
saveToJWT set, but the group does not, the field will be included at the top level of the token.
Modern browsers automatically include
http-only cookies when making requests directly to URLs—meaning that if you are running your API on http://example.com, and you have logged in and visit http://example.com/test-page, your browser will automatically include the Payload authentication cookie for you.
However, if you use
fetch or similar APIs to retrieve Payload resources from its REST or GraphQL API, you need to specify to include credentials (cookies).
Fetch example, including credentials:
For more about how to automatically include cookies in requests from your app to your Payload API, click here.
CSRF (cross-site request forgery) attacks are common and dangerous. By using an HTTP-only cookie, Payload removes many XSS vulnerabilities, however, CSRF attacks can still be possible.
For example, let's say you have a very popular app running at coolsite.com. This app allows users to manage finances and send / receive money. As Payload is using HTTP-only cookies, that means that browsers automatically will include cookies when sending requests to your domain - no matter what page created the request.
So, if a user of coolsite.com is logged in and just browsing around on the internet, they might stumble onto a page with bad intentions. That bad page might automatically make requests to all sorts of sites to see if they can find one that they can log into - and coolsite.com might be on their list. If your user was logged in while they visited that evil site, the attacker could do whatever they wanted as if they were your coolsite.com user by just sending requests to the coolsite API (which would automatically include the auth cookie). They could send themselves a bunch of money from your user's account, change the user's password, etc. This is what a CSRF attack is.
To define domains that should allow users to identify themselves via the Payload HTTP-only cookie, use the
csrf option on the base Payload config to whitelist domains that you trust.
In addition to authenticating via an HTTP-only cookie, you can also identify users via the
Authorization header on an HTTP request.
You can retrieve a user's token via the response to
me auth operations.