@otosense/jwt-middleware v4.5.1

jwt-middleware

Express middleware that validates a JSON web token for each request and adds a token property to the request object containing the fields from the validated token.

Usage

import accessControl from 'api_access_control';
import express from 'express';

accessControl.setSecret('an RSA public key or secret phrase');
accessControl.setInternalSecret('even more secret phrase');
accessControl.setIssuer('api.otosense.ai');

const app: express.Application = express();

// req.token will have the shape
// { account: string, deviceId: string }
app.use('/device', accessControl.validateJWT(['accountId', 'deviceId', 'channelId']));

// req.token will have the shape
// { account: string, email: string }
app.use('/model', accessControl.validateJWT(['account', 'userId']));

// a token without an 'accessControl' property that contains 'administrator'
// will be rejected and a 403 response returned.
app.use('/admin', accessControl.validateJWT(['accountId', 'userId'], ['administrator']));

// for internal endpoints only
app.use('/internal', accessControl.authenticateInternal);

// enable max age validation
accessControl.checkMaxAge(true);

// disable max age validation
accessControl.checkMaxAge(false);

Exports

• function setSecret(secret: string): void A secret must be set in order to validate tokens.
• function setInternalSecret(secret: string): void This secret will be used to authenticate requests for internal endpoints.
• function setIssuer(issuer: string): void Set the expected issuer value to check at validation (optional).
• function setMaxAge(maxAge: string | number): void Set max age in milliseconds or parseable string (default is '20m')
• function validateJWT(tokenFields: string[], requiredAccessLevels: string[] = []): (req, res, next) => void
• function authenticateInternal(req, res, next): void
• function checkMaxAge(enable: boolean): void

Notes

Requests must include an Authorization header with the format 'Bearer eyJhbG...'. A 401 Unauthorized response will be returned if:

• There is no Authorization header
• The Authorization header does not begin with 'Bearer '
• The token does not pass signature validation (i.e. it has expired or was generated with a different secret)
• The token does not contain all of the claims listed in the tokenFields argument to validateJWT

A 403 Forbidden response will be returned if a requiredAccessLevel argument was passed to validateJWT and:

• The token does not contain an accessLevels claim, or
• The token's accessLevels value is not an array containing the given requiredAccessLevel

Changelog

Version 1.0.0

• Changed 'bearer ' to 'Bearer ' to match standard (for compatibility with Postman)
• Removed propertyName argument from validateJWT function so the property added to req will always be token, for route schema portability
• Corrected documentation

Version 2.0.0

• Now expects a base64-encoded secret, which will be decoded before token verification

Version 3.0.0

• Now expects an unencoded secret

Version 3.1.0

• Added setInternalSecret and authenticateInternal methods

Version 4.0.0

• Removed maxAge validation by default and added the checkMaxAge function to enable it if desired.