serviceberry-jwt
Version:
JSON Web Token authentication for Serviceberry
143 lines (91 loc) • 5.22 kB
Markdown
serviceberry-jwt
=================
[](https://circleci.com/gh/bob-gray/serviceberry-jwt)
[](https://codeclimate.com/github/bob-gray/serviceberry-jwt/test_coverage)
[](https://codeclimate.com/github/bob-gray/serviceberry-jwt/maintainability)
[](https://badge.fury.io/js/serviceberry-jwt)
JSON Web Token plugin for [Serviceberry](https://serviceberry.js.org). For information
about JSON Web Tokens see [RFC 7519](https://tools.ietf.org/html/rfc7519).
Install
-------
```shell-script
npm install serviceberry-jwt
```
Usage
-----
Fails the request with a `401 Unauthorized` status if the token is not found, is not formatted correctly, or
if the key doesn't verify the signature.
This plugin exports an abstract class `Jwt` for extending by your authorization class that knows how to fetch your
token keys. To use this plugin extend `Jwt` and implement at least `getKey(id)`. The key is then used to verify
the request's token. You can extend the validation by overriding `validate(request)` or change the process of finding
a request's token by overriding `getToken(request)`.
```js
const Jwt = require("serviceberry-jwt");
class Auth extends Jwt {
getKey (id) {
return data.getKey(id); // can also return a promise or use async/await
}
async validate (request) { // you can override validate to go beyond just verifying the token signature
await super.validate(...arguments); // will throw if token is not verified
... // test scopes or other custom payload properties
}
}
trunk.use(new Auth(verifyOptions, options));
```
verifyOptions *object*
----------------------
See [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken#user-content-jwtverifytoken-secretorpublickey-options-callback)
for verify options.
options *object*
----------------
- **scheme** *string*
The authentication scheme. Used to get the token from the request and to set the `WWW-Authenticate`
response header scheme when responding with `401 Unauthorized`. Defaults to `Bearer`.
- *Bearer*
When the scheme is *Bearer* the plugin will look for the token in the request's
`Authorization` header.
- *Token*
When the scheme is *Token* the plugin will look for the token in the request's
parameters by it's name (see *param* below). `request.getParam(options.param)`.
- **accessToken** *boolean*
When *scheme* is `Bearer` and `accessToken` is `true`, first look for the token in the `Authorization` header
and if it isn't found look for `access_token` as described below. Defaults to `false`. This option has no
purpose if *scheme* is `Token`. Per [RFC 6750](https://tools.ietf.org/html/rfc6750) sections 2.2 & 2.3.
- Find bearer token in a form encoded body parameter named `access_token` for request methods with defined
body semantics (*POST, PUT, and PATCH*).
- Find bearer token in a query string parameter named `access_token` for request methods without defined
body semantics (*not POST, PUT, or PATCH*).
- **param** *string*
When *scheme* is `Token`, *param* is the name of the request parameter where the token should be found.
Defaults to `token`. This can be any type of request parameter - path, query string, or body. This option
has no purpose if scheme is `Bearer`.
Jwt
---
Abstract class
### constructor([verifyOptions[, options]])
- **verifyOptions** *object*
Sets `this.verifyOptions`. Passed to `jwt.verify()`. See
[jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken#user-content-jwtverifytoken-secretorpublickey-options-callback)
- **options**
Sets `this.options`. See [options](#options) above.
### getKey(id)
**You must extend this class and at least implement this method.**
Called by the `validate` method for fetching a signing key used to verify a token.
- **id** *string*
The id which identifies the key to be used to verify the token.
### use(request, response)
The [handler](https://serviceberry.js.org/docs/handlers) method. This is the method called by Serviceberry.
Sets `request.jwt`. This is an `async` function.
- **request** *object*
Serviceberry [`request`](https://serviceberry.js.org/docs/request) object.
- **response** *object*
Serviceberry [`response`](https://serviceberry.js.org/docs/response) object.
### validate(request)
Called by the `use` method to validate the token. This is an `async` function and should return
or resolve to a boolean value or throw an error.
- **request** *object*
Serviceberry [`request`](https://serviceberry.js.org/docs/request) object.
### getToken(request)
Called by the `use` method to find the request's token.
- **request** *object*
Serviceberry [`request`](https://serviceberry.js.org/docs/request) object.