{"id":14969151,"url":"https://github.com/fastify/fastify-basic-auth","last_synced_at":"2025-05-16T01:06:23.360Z","repository":{"id":38361454,"uuid":"134830147","full_name":"fastify/fastify-basic-auth","owner":"fastify","description":"Fastify Basic auth plugin","archived":false,"fork":false,"pushed_at":"2025-04-24T18:51:21.000Z","size":165,"stargazers_count":84,"open_issues_count":1,"forks_count":27,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-04-24T19:43:12.265Z","etag":null,"topics":["authentication","basic","fastify","fastify-plugin"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@fastify/basic-auth","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"fastify","open_collective":"fastify"}},"created_at":"2018-05-25T08:50:20.000Z","updated_at":"2025-04-24T18:51:25.000Z","dependencies_parsed_at":"2023-02-06T17:05:11.241Z","dependency_job_id":"7d10ac0e-e5ae-4832-801c-13a6c4b6b4e5","html_url":"https://github.com/fastify/fastify-basic-auth","commit_stats":{"total_commits":160,"total_committers":21,"mean_commits":7.619047619047619,"dds":0.675,"last_synced_commit":"36277998e1963902c497c6f07b78b63390bc9738"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-basic-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-basic-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-basic-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-basic-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastify","download_url":"https://codeload.github.com/fastify/fastify-basic-auth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448579,"owners_count":22072764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","basic","fastify","fastify-plugin"],"created_at":"2024-09-24T13:41:13.818Z","updated_at":"2025-05-16T01:06:18.352Z","avatar_url":"https://github.com/fastify.png","language":"JavaScript","readme":"# @fastify/basic-auth\n\n[![CI](https://github.com/fastify/fastify-basic-auth/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/fastify-basic-auth/actions/workflows/ci.yml)\n[![NPM version](https://img.shields.io/npm/v/@fastify/basic-auth.svg?style=flat)](https://www.npmjs.com/package/@fastify/basic-auth)\n[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)\n\n A simple [Basic auth](https://datatracker.ietf.org/doc/html/rfc7617) plugin for Fastify.\n\n ## Install\n```\nnpm i @fastify/basic-auth\n```\n\n### Compatibility\n| Plugin version | Fastify version |\n| ---------------|-----------------|\n| `\u003e=6.x`        | `^5.x`          |\n| `^4.x`         | `^4.x`          |\n| `\u003e=1.x \u003c4.x`   | `^3.x`          |\n| `^0.x`         | `^2.x`          |\n| `^0.x`         | `^1.x`          |\n\n\nPlease note that if a Fastify version is out of support, then so are the corresponding versions of this plugin\nin the table above.\nSee [Fastify's LTS policy](https://github.com/fastify/fastify/blob/main/docs/Reference/LTS.md) for more details.\n\n## Usage\nThis plugin decorates the fastify instance with a `basicAuth` function, which can be used inside any hook before a route handler, or with [`@fastify/auth`](https://github.com/fastify/fastify-auth).\n\n```js\nconst fastify = require('fastify')()\nconst authenticate = {realm: 'Westeros'}\nfastify.register(require('@fastify/basic-auth'), { validate, authenticate })\n// `this` inside validate is `fastify`\nfunction validate (username, password, req, reply, done) {\n  if (username === 'Tyrion' \u0026\u0026 password === 'wine') {\n    done()\n  } else {\n    done(new Error('Winter is coming'))\n  }\n}\n\nfastify.after(() =\u003e {\n  fastify.addHook('onRequest', fastify.basicAuth)\n\n  fastify.get('/', (req, reply) =\u003e {\n    reply.send({ hello: 'world' })\n  })\n})\n```\n\nPromises and *async/await* are supported as well!\n```js\nconst fastify = require('fastify')()\nconst authenticate = {realm: 'Westeros'}\nfastify.register(require('@fastify/basic-auth'), { validate, authenticate })\nasync function validate (username, password, req, reply) {\n  if (username !== 'Tyrion' || password !== 'wine') {\n    return new Error('Winter is coming')\n  }\n}\n```\n\nUse with `onRequest`:\n```js\nconst fastify = require('fastify')()\nconst authenticate = {realm: 'Westeros'}\nfastify.register(require('@fastify/basic-auth'), { validate, authenticate })\nasync function validate (username, password, req, reply) {\n  if (username !== 'Tyrion' || password !== 'wine') {\n    return new Error('Winter is coming')\n  }\n}\n\nfastify.after(() =\u003e {\n  fastify.route({\n    method: 'GET',\n    url: '/',\n    onRequest: fastify.basicAuth,\n    handler: async (req, reply) =\u003e {\n      return { hello: 'world' }\n    }\n  })\n})\n```\n\nUse with [`@fastify/auth`](https://github.com/fastify/fastify-auth):\n```js\nconst fastify = require('fastify')()\nconst authenticate = {realm: 'Westeros'}\nfastify.register(require('@fastify/auth'))\nfastify.register(require('@fastify/basic-auth'), { validate, authenticate })\nasync function validate (username, password, req, reply) {\n  if (username !== 'Tyrion' || password !== 'wine') {\n    return new Error('Winter is coming')\n  }\n}\n\nfastify.after(() =\u003e {\n  // use preHandler to authenticate all the routes\n  fastify.addHook('preHandler', fastify.auth([fastify.basicAuth]))\n\n  fastify.route({\n    method: 'GET',\n    url: '/',\n    // use onRequest to authenticate just this one\n    onRequest: fastify.auth([fastify.basicAuth]),\n    handler: async (req, reply) =\u003e {\n      return { hello: 'world' }\n    }\n  })\n})\n```\n\n### Custom error handler\n\nOn failed authentication, `@fastify/basic-auth` calls the Fastify\n[generic error\nhandler](https://fastify.dev/docs/latest/Reference/Server/#seterrorhandler) with an error\nand sets `err.statusCode` to `401`.\n\nTo properly `401` errors:\n\n```js\nfastify.setErrorHandler(function (err, req, reply) {\n  if (err.statusCode === 401) {\n    // This was unauthorized! Display the correct page/message\n    reply.code(401).send({ was: 'unauthorized' })\n    return\n  }\n  reply.send(err)\n})\n```\n\n## Options\n\n### `utf8` \u003cBoolean\u003e (optional, default: true)\n\nUser-ids or passwords with non-US-ASCII characters may cause issues\nunless both parties agree on the encoding scheme. Setting `utf8` to\ntrue sends the 'charset' parameter to prefer \"UTF-8\", increasing the\nlikelihood that clients will use that encoding.\n\n### `strictCredentials` \u003cBoolean\u003e (optional, default: true)\n\nSetting `strictCredentials` to false allows additional whitespaces at\nthe beginning, middle, and end of the authorization header.\nThis is a fallback option to ensure the same behavior as `@fastify/basic-auth`\nversion \u003c=5.x.\n\n### `validate` \u003cFunction\u003e (required)\n\nThe `validate` function is called on each request made\nand is passed the `username`, `password`, `req`, and `reply`\nparameters, in that order. An optional fifth parameter, `done`, can be\nused to signify a valid request when called with no arguments\nor an invalid request when called with an `Error` object. Alternatively,\nthe `validate` function can return a promise, resolving for valid\nrequests and rejecting for invalid. This can also be achieved using\nan `async/await` function, and throwing for invalid requests.\n\nSee code above for examples.\n\n### `authenticate` \u003cBoolean|Object\u003e (optional, default: false)\n\nThe `authenticate` option adds the [`WWW-Authenticate` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate) and can set the `realm` value.\n\nThis can trigger client-side authentication interfaces, such as the browser authentication dialog.\n\nSetting `authenticate` to `true` adds the header `WWW-Authenticate: Basic`. When `false`, no header is added (default).\n\n```js\nfastify.register(require('@fastify/basic-auth'), {\n  validate,\n  authenticate: true // WWW-Authenticate: Basic\n})\n\nfastify.register(require('@fastify/basic-auth'), {\n  validate,\n  authenticate: false // no authenticate header, same as omitting authenticate option\n})\n```\n\nThe `authenticate` option can have a `realm` key when supplied as an object.\nIf the `realm` key is supplied, it will be appended to the header value:\n\n```js\nfastify.register(require('@fastify/basic-auth'), {\n  validate,\n  authenticate: {realm: 'example'} // WWW-Authenticate: Basic realm=\"example\"\n})\n```\n\nThe `realm` key can also be a function:\n\n```js\nfastify.register(require('@fastify/basic-auth'), {\n  validate,\n  authenticate: {\n    realm(req) {\n      return 'example' // WWW-Authenticate: Basic realm=\"example\"\n    }\n  }\n})\n```\n\n### `header` String (optional)\n\nThe `header` option specifies the header name to get credentials from for validation.\n\n```js\nfastify.register(require('@fastify/basic-auth'), {\n  validate,\n  header: 'x-forwarded-authorization'\n})\n```\n\n## License\n\nLicensed under [MIT](./LICENSE).\n","funding_links":["https://github.com/sponsors/fastify","https://opencollective.com/fastify"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Ffastify-basic-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastify%2Ffastify-basic-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Ffastify-basic-auth/lists"}