Custom Strategies

Creating a strategy

At the core, a strategy is a way to authenticate a user making a request. As of 3.0 we moved away from Passport in favor of pulling back the curtain and putting you in full control.

A strategy is made up of the following:

Parameter	Description
`name` *	The name of your strategy
`authenticate` *	A function that takes in the parameters below and returns a user or null.

The authenticate function is passed the following arguments:

Argument	Description
`headers` *	The headers on the incoming request. Useful for retrieving identifiable information on a request.
`payload` *	The Payload class. Useful for authenticating the identifiable information against Payload.
`isGraphQL`	Whether or not the request was made from a GraphQL endpoint. Default is `false`.

Example Strategy

At its core a strategy simply takes information from the incoming request and returns a user. This is exactly how Payload's built-in strategies function.

Your authenticate method should return an object containing a Payload user document and any optional headers that you'd like Payload to set for you when we return a response.

1import { CollectionConfig } from 'payload'
2
3export const Users: CollectionConfig = {
slug: 'users',
auth: {
  disableLocalStrategy: true,
  strategies: [
    {
      name: 'custom-strategy',
      authenticate: ({ payload, headers }) => {
        const usersQuery = await payload.find({
          collection: 'users',
          where: {
            code: {
              equals: headers.get('code'),
            },
            secret: {
              equals: headers.get('secret'),
            },
          },
        })
22
        return {
          // Send the user back to authenticate,
          // or send null if no user should be authenticated
          user: usersQuery.docs[0] || null,
27
          // Optionally, you can return headers
          // that you'd like Payload to set here when
          // it returns the response
          responseHeaders: new Headers({
            'some-header': 'my header value'
          })
        }
      }
    }
  ]
},
fields: [
  {
    name: 'code',
    type: 'text',
    index: true,
    unique: true,
  },
  {
    name: 'secret',
    type: 'text',
  },
]
51}

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

Custom Strategies

Creating a strategy

Example Strategy

Token Data

On this page