@fastify/auth

Note that @fastify/auth does not provide authentication strategies itself. You must provide your own validation logic, typically by decorating the Fastify instance or using another plugin. @fastify/auth acts as a utility to compose these strategies into logical groups (using and or or relations) and apply them to routes or hooks.

Strategies can be implemented using:

• Callbacks: (request, reply, done) => { ... }
• Promises: Functions that return a Promise.
• Async functions: async (request, reply) => { ... } (Note: if using async, do not call the done parameter to avoid multiple handler calls).

fastify
  .decorate('verifyJWT', function (request, reply, done) {
    // your validation logic
    done() // pass an error if authentication fails
  })
  .register(require('@fastify/auth'))
  .after(() => {
    fastify.route({
      method: 'POST',
      url: '/secure',
      preHandler: fastify.auth([fastify.verifyJWT]),
      handler: (req, reply) => reply.send({ hello: 'world' })
    })
  })

You can combine multiple authentication functions using logical and or or relations. By default, the relation is or.

Basic Relations

• OR (Default): The request succeeds if at least one strategy succeeds.
• AND: The request succeeds only if all strategies succeed.

Composite Authentication (Nested Arrays)

For complex logic, use nested arrays. The relation of a sub-array is always the opposite of the main relation:

• If the main relation is or, sub-arrays use and.
• If the main relation is and, sub-arrays use or.

Run All Strategies

By default, any successful authentication stops the rest of the chain. To execute every strategy regardless of success/failure (useful for attaching business data to the request), use the run: 'all' option.

// Example: (verifyUserPassword AND verifyLevel) OR (verifyVIP)
fastify.route({
  method: 'POST',
  url: '/auth-multiple',
  preHandler: fastify.auth([
    [fastify.verifyUserPassword, fastify.verifyLevel],
    fastify.verifyVIP
  ], {
    relation: 'or' // default
  }),
  handler: (req, reply) => reply.send({ hello: 'world' })
})

The @fastify/auth plugin uses logical relations to determine if a request is authenticated based on an array of functions.

Relation Logic

The run option

By default, the plugin stops processing as soon as the relation requirement is met (e.g., the first successful function in an 'or' relation).

If you set run: 'all' in the options object, the plugin will continue to execute all provided functions regardless of whether the authentication requirement has already been satisfied or failed. This is useful if you need side effects from all authentication attempts.

// Example: Requiring ALL strategies to pass, but running all even if one fails
fastify.get('/strict', {
  auth: fastify.auth([auth1, auth2], { relation: 'and', run: 'all' })
}, handler)

Once registered, the plugin decorates your Fastify instance with an auth method. You use this method within your route handlers to apply one or more authentication functions (strategies).

Arguments

fastify.auth(functions, opts)

• functions: An array of authentication functions. These functions can be single functions or arrays of functions (sub-arrays).
• opts: An optional configuration object:
  • relation: 'or' or 'and'. Determines how the functions in the array are evaluated. Note that sub-arrays use the inverse logic of the parent array.
  • run: If set to 'all', the plugin will attempt to run all authentication functions even if one fails. Otherwise, it stops at the first failure (for 'and') or first success (for 'or'). Must be set to 'all' if used.

Authentication Function Signature

Each authentication function must follow the standard Fastify hook signature: function(request, reply, done) { ... }.

They can be synchronous (calling done()) or return a Promise.

// Example: Applying multiple auth strategies to a route
fastify.get('/protected', { auth: fastify.auth([strategyOne, [strategyTwo, strategyThree]]) }, (request, reply) => {
  reply.send({ authenticated: true })
})