serviceberry-jwt v0.3.1

serviceberry-jwt

JSON Web Token plugin for Serviceberry. For information about JSON Web Tokens see RFC 7519.

Install

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

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

• options

  Sets this.options. See 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 method. This is the method called by Serviceberry. Sets request.jwt. This is an async function.

• request object

  Serviceberry request object.

• response object

  Serviceberry 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 object.

getToken(request)

Called by the use method to find the request's token.

• request object

  Serviceberry request object.