@fastify/bearer-auth

Install the plugin using npm to add Bearer authentication support to your Fastify application.

npm i @fastify/bearer-auth

Instead of providing a static list of keys, you can provide an auth function. This is useful for looking up tokens in a database or performing more complex validation logic.

The auth function is called with (key, request). It can be a synchronous function or an asynchronous function (returning a Promise). It must return a truthy value to authorize the request, or false to deny it. If the function throws an error or returns a rejected promise, the plugin will respond with a 500 Internal Server Error.

Note: When auth is provided, the keys option is ignored.

const options = {
  auth: async (key, request) => {
    const user = await database.findUserByToken(key)
    return !!user // Return true if user exists, false otherwise
  }
}

The specCompliance option controls how the Authorization header prefix is validated:

• rfc6750 (Default): The prefix is case-sensitive and must match the bearerType exactly (e.g., if bearerType is 'Bearer', the header must start with 'Bearer ').
• rfc6749: The prefix is case-insensitive (e.g., if bearerType is 'Bearer', the header can start with 'bearer ' or 'Bearer ').

If you set addHook: false in the plugin options, the plugin will not automatically intercept requests. Instead, it decorates the Fastify instance, allowing you to manually trigger authentication logic.

It provides two decorations:

1. fastify.verifyBearerAuthFactory: A factory function to create custom verification functions.
2. fastify.verifyBearerAuth: A pre-configured verification function based on the plugin's initial options.

fastify.register(require('@fastify/bearer-auth'), {
  addHook: false
})

// Use the decorated verification function in a specific route
fastify.get('/protected', { preHandler: fastify.verifyBearerAuth }, async (request, reply) => {
  return { hello: 'world' }
})

Register @fastify/bearer-auth with your Fastify instance to handle Bearer token authentication. By default, the plugin adds an onRequest hook to your application that validates the Authorization: Bearer <token> header.

To use the plugin, call fastify.register(require('@fastify/bearer-auth'), options).

const fastify = require('fastify')()

fastify.register(require('@fastify/bearer-auth'), {
  // options
})

To use the plugin, register it with a keys option containing a Set or array of valid strings. By default, it registers an onRequest hook that protects all routes within its scope.

'use strict'

const fastify = require('fastify')()
const bearerAuthPlugin = require('@fastify/bearer-auth')
const keys = new Set(['a-super-secret-key', 'another-super-secret-key'])

fastify.register(bearerAuthPlugin, {keys})
fastify.get('/foo', (req, reply) => {
  reply.send({authenticated: true})
})

fastify.listen({port: 8000}, (err) => {
  if (err) {
    fastify.log.error(err.message)
    process.exit(1)
  }
  fastify.log.info('http://127.0.0.1:8000/foo')
})

When registering the plugin, you can provide the following configuration options:

• addHook: Determines which Fastify hook is used for authentication.
  • Supported values: 'onRequest', 'preParsing', or false.
  • If set to true or omitted, it defaults to 'onRequest'.
  • If set to false, the plugin will not add a hook but will instead decorate the Fastify instance with authentication functions.
  • Note: Using 'preParsing' is useful for protecting against DoS attacks.
• verifyErrorLogLevel: Specifies which method on fastify.log should be used to log verification errors.
  • Defaults to 'error'.
  • Must be a valid function name existing on the fastify.log object (e.g., 'error', 'warn').
  • If fastify.log does not support the specified level, or if the log object is invalid, the level is set to null.

Ensure your Fastify version is compatible with the version of @fastify/bearer-auth you are using:

During request processing, the plugin throws specific errors if the Authorization header is missing or malformed. These errors are associated with HTTP status code 401.

// Error codes for request authentication:
FST_BEARER_AUTH_MISSING_AUTHORIZATION_HEADER: 'missing authorization header' (HTTP 401)
FST_BEARER_AUTH_INVALID_AUTHORIZATION_HEADER: 'invalid authorization header' (HTTP 401)

When registering the @fastify/bearer-auth plugin, you may encounter specific error codes if the provided options do not match the required schema. These errors are thrown during the plugin registration phase.

// Error codes for configuration validation:
FST_BEARER_AUTH_INVALID_KEYS_OPTION_TYPE: 'options.keys has to be an Array or a Set'
FST_BEARER_AUTH_INVALID_HOOK: 'options.addHook must be either "onRequest" or "preParsing"'
FST_BEARER_AUTH_INVALID_LOG_LEVEL: 'fastify.log does not have level 	ext{'%s'}'
FST_BEARER_AUTH_KEYS_OPTION_INVALID_KEY_TYPE: 'options.keys has to contain only string entries'
FST_BEARER_AUTH_INVALID_SPEC: 'options.specCompliance has to be set to \'rfc6750\' or \'rfc6749\''