fastify-basic-auth
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.0 • Public • Published

    fastify-basic-auth

    CI NPM version Known Vulnerabilities js-standard-style

    A simple basic auth plugin for Fastify.

    Install

    npm i fastify-basic-auth
    

    Usage

    This plugin decorates the fastify instance with a basicAuth function, which you can use inside any hook before your route handler, or with fastify-auth.

    const fastify = require('fastify')()
    const authenticate = {realm: 'Westeros'}
    fastify.register(require('fastify-basic-auth'), { validate, authenticate })
    // `this` inside validate is `fastify`
    function validate (username, password, req, reply, done) {
      if (username === 'Tyrion' && password === 'wine') {
        done()
      } else {
        done(new Error('Winter is coming'))
      }
    }
    
    fastify.after(() => {
      fastify.addHook('onRequest', fastify.basicAuth)
    
      fastify.get('/', (req, reply) => {
        reply.send({ hello: 'world' })
      })
    })

    Promises and async/await are supported as well!

    const fastify = require('fastify')()
    const authenticate = {realm: 'Westeros'}
    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')
      }
    }

    Use with onRequest:

    const fastify = require('fastify')()
    const authenticate = {realm: 'Westeros'}
    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(() => {
      fastify.route({
        method: 'GET',
        url: '/',
        onRequest: fastify.basicAuth,
        handler: async (req, reply) => {
          return { hello: 'world' }
        }
      })
    })

    Use 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 will call the Fastify generic error handler with an error. fastify-basic-auth sets the err.statusCode property to 401.

    In order 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

    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 may 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 may 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.

    See code above for examples.

    authenticate <Boolean|Object> (optional, default: false)

    When supplied, the authenticate option will cause the WWW-Authenticate header to be added. It may also be used to set the realm value.

    This can be useful in situations where we want to trigger client-side authentication interfaces - for instance the browser authentication dialog.

    As a boolean setting authenticate to true will set a header like so: WWW-Authenticate: Basic. When false, no header is added. This is the default.

    fastify.register(require('fastify-basic-auth'), {
      validate,
      authenticate: true // WWW-Authenticate: Basic
    })
    
    fastify.register(require('fastify-basic-auth'), {
      validate,
      authenticate: false // no authenticate header, same as omitting authenticate option
    })

    When supplied as an object the authenticate option may have a realm key.

    If the realm key is supplied, it will be appended to the header value:

    fastify.register(require('fastify-basic-auth'), {
      validate,
      authenticate: {realm: 'example'} // WWW-Authenticate: Basic realm="example"
    })

    The realm key could also be a function:

    fastify.register(require('fastify-basic-auth'), {
      validate,
      authenticate: {
        realm(req) {
          return 'example' // WWW-Authenticate: Basic realm="example"
        }
      }
    })

    header String (optional)

    When supplied, the header option is the name of the header to get credentials from for validation.

    fastify.register(require('fastify-basic-auth'), {
      validate,
      header: 'x-forwarded-authorization'
    })

    License

    Licensed under MIT.

    Install

    npm i fastify-basic-auth

    DownloadsWeekly Downloads

    10,697

    Version

    2.2.0

    License

    MIT

    Unpacked Size

    31.4 kB

    Total Files

    10

    Last publish

    Collaborators

    • coopflow
    • simoneb
    • rafaelgss
    • starptech
    • delvedor
    • matteo.collina
    • allevo
    • jsumners
    • zekth
    • ethan_arrowood
    • eomm
    • fox1t
    • salmanm
    • davidmarkclements
    • airhorns
    • kibertoad
    • climba03003