Please note that if a Fastify version is out of support, then so are the corresponding versions of this plugin
in the table above.
See Fastify's LTS policy for more details.
Usage
This plugin decorates the fastify instance with a basicAuth function, which can be used inside any hook before a route handler, or with @fastify/auth.
const fastify = require('fastify')()const authenticate = {realm: 'Westeros'}fastify.register(require('@fastify/auth'))fastify.register(require('@fastify/basic-auth'), { validate, authenticate })async function validate (username, password, req, reply) { if (username !== 'Tyrion' || password !== 'wine') { return new Error('Winter is coming') }}fastify.after(() => { // use preHandler to authenticate all the routes fastify.addHook('preHandler', fastify.auth([fastify.basicAuth])) fastify.route({ method: 'GET', url: '/', // use onRequest to authenticate just this one onRequest: fastify.auth([fastify.basicAuth]), handler: async (req, reply) => { return { hello: 'world' } } })})
Custom error handler
On failed authentication, @fastify/basic-auth calls the Fastify
generic error
handler with an error
and sets err.statusCode to 401.
To properly 401 errors:
fastify.setErrorHandler(function (err, req, reply) { if (err.statusCode === 401) { // This was unauthorized! Display the correct page/message reply.code(401).send({ was: 'unauthorized' }) return } reply.send(err)})
Options
utf8 (optional, default: true)
User-ids or passwords with non-US-ASCII characters may cause issues
unless both parties agree on the encoding scheme. Setting utf8 to
true sends the 'charset' parameter to prefer "UTF-8", increasing the
likelihood that clients will use that encoding.
strictCredentials (optional, default: true)
Setting strictCredentials to false allows additional whitespaces at
the beginning, middle, and end of the authorization header.
This is a fallback option to ensure the same behavior as @fastify/basic-auth
version <=5.x.
validate (required)
The validate function is called on each request made
and is passed the username, password, req, and reply
parameters, in that order. An optional fifth parameter, done, can be
used to signify a valid request when called with no arguments
or an invalid request when called with an Error object. Alternatively,
the validate function can return a promise, resolving for valid
requests and rejecting for invalid. This can also be achieved using
an async/await function, and throwing for invalid requests.
Setting the proxyMode to true will make the plugin implement HTTP proxy authentication, rather than resource authentication. In other words, the plugin will:
read credentials from the Proxy-Authorization header rather than Authorization
use 407 response status code instead of 401 to signal missing or invalid credentials
use the Proxy-Authenticate header rather than WWW-Authenticate if the authenticate option is set
header String (optional)
The header option specifies the header name to get credentials from for validation. If not specified it defaults to Authorization or Proxy-Authorization (according to the value of proxyMode option)