Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update references to old fastify-* modules #86

Merged
merged 1 commit into from
Apr 29, 2022
Merged

docs: update references to old fastify-* modules #86

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
# fastify-basic-auth
# @fastify/basic-auth

![CI](https://github.com/fastify/fastify-basic-auth/workflows/CI/badge.svg?branch=master)
[![NPM version](https://img.shields.io/npm/v/fastify-basic-auth.svg?style=flat)](https://www.npmjs.com/package/fastify-basic-auth)
[![NPM version](https://img.shields.io/npm/v/@fastify/basic-auth.svg?style=flat)](https://www.npmjs.com/package/@fastify/basic-auth)
[![Known Vulnerabilities](https://snyk.io/test/github/fastify/fastify-basic-auth/badge.svg)](https://snyk.io/test/github/fastify/fastify-basic-auth)
[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)

A simple basic auth plugin for Fastify.

## Install
```
npm i fastify-basic-auth
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`](https://github.com/fastify/fastify-auth).
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`](https://github.com/fastify/fastify-auth).

```js
const fastify = require('fastify')()
const authenticate = {realm: 'Westeros'}
fastify.register(require('fastify-basic-auth'), { validate, authenticate })
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') {
Expand All @@ -40,7 +40,7 @@ Promises and *async/await* are supported as well!
```js
const fastify = require('fastify')()
const authenticate = {realm: 'Westeros'}
fastify.register(require('fastify-basic-auth'), { validate, authenticate })
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')
Expand All @@ -52,7 +52,7 @@ Use with `onRequest`:
```js
const fastify = require('fastify')()
const authenticate = {realm: 'Westeros'}
fastify.register(require('fastify-basic-auth'), { validate, authenticate })
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')
Expand All @@ -71,12 +71,12 @@ fastify.after(() => {
})
```

Use with [`fastify-auth`](https://github.com/fastify/fastify-auth):
Use with [`@fastify/auth`](https://github.com/fastify/fastify-auth):
```js
const fastify = require('fastify')()
const authenticate = {realm: 'Westeros'}
fastify.register(require('fastify-auth'))
fastify.register(require('fastify-basic-auth'), { validate, authenticate })
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')
Expand All @@ -101,10 +101,10 @@ fastify.after(() => {

### Custom error handler

On failed authentication, *fastify-basic-auth* will call the Fastify
On failed authentication, *@fastify/basic-auth* will call the Fastify
[generic error
handler](https://www.fastify.io/docs/latest/Server/#seterrorhandler) with an error.
*fastify-basic-auth* sets the `err.statusCode` property to `401`.
*@fastify/basic-auth* sets the `err.statusCode` property to `401`.

In order to properly `401` errors:

Expand Down Expand Up @@ -144,12 +144,12 @@ This can be useful in situations where we want to trigger client-side authentica
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.

```js
fastify.register(require('fastify-basic-auth'), {
fastify.register(require('@fastify/basic-auth'), {
validate,
authenticate: true // WWW-Authenticate: Basic
})

fastify.register(require('fastify-basic-auth'), {
fastify.register(require('@fastify/basic-auth'), {
validate,
authenticate: false // no authenticate header, same as omitting authenticate option
})
Expand All @@ -160,7 +160,7 @@ 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:

```js
fastify.register(require('fastify-basic-auth'), {
fastify.register(require('@fastify/basic-auth'), {
validate,
authenticate: {realm: 'example'} // WWW-Authenticate: Basic realm="example"
})
Expand All @@ -169,7 +169,7 @@ fastify.register(require('fastify-basic-auth'), {
The `realm` key could also be a function:

```js
fastify.register(require('fastify-basic-auth'), {
fastify.register(require('@fastify/basic-auth'), {
validate,
authenticate: {
realm(req) {
Expand All @@ -185,7 +185,7 @@ When supplied, the header option is the name of the header to get
credentials from for validation.

```js
fastify.register(require('fastify-basic-auth'), {
fastify.register(require('@fastify/basic-auth'), {
validate,
header: 'x-forwarded-authorization'
})
Expand Down