@tsmx/express-jwt-validator

@tsmx/express-jwt-validator

Simple express middleware for validating JWT bearer tokens.

Stop writing boilerplate to protect express routes with JWT bearer tokens in your projects.

Supports optional log output using winston or any compatible logger.

Usage

const express = require('express');
const app = express();

const verifyToken = require('@tsmx/express-jwt-validator')({ secret: 'YOUR_JWT_SECRET' });

app.get('/secret', verifyToken, (req, res) => {
  res.status(200).send('This route can only be accessed with a valid JWT bearer token.');
});

For further customizing please refer to the configuration options.

How it works

This module exports a middleware function for express to check a request for a valid JSON Web token authorization. The token must be provided as a bearer token in the HTTP request header according to the RFC standard.

Requests with a failed JWT validation will be rejected with HTTP status 401 by default. If the validations succeeds, the verified JWT payload will be added to the rquest and it will be passed to the next element of the middleware chain.

Configuration options

When requiring in the middleware with...

const verifyToken = require('@tsmx/express-jwt-validator')({ /* configuration object */ });

...the passed configuration object supports the following porperties.

secret

Type: String

Default: undefined

Mandatory: yes

The sceret used to verify the JWT bearer token. Must be present, otherwise an expection will be thrown.

Example:

const verifyToken = require('@tsmx/express-jwt-validator')({ secret: 'MySecretKey-123456' });

header

Type: String

Default: authorization

Mandatory: no

Can be used if the bearer token will be supplied in another header field then authorization (Note: HTTP header field names are case-insensitive).

Example:

const verifyToken = require('@tsmx/express-jwt-validator')({ 
  secret: 'MySecretKey-123456', 
  header: 'auth' 
});

rejectHttpStatus

Type: Number

Default: 401

Mandatory: no

The HTTP status to be sent back to the client if the bearer token validation fails. Defaults to 401 for Unauthorized, could also be set to 403 Forbidden for example. Please note that although any status is possible here you should use an appropriate HTTP client error code.

Example:

const verifyToken = require('@tsmx/express-jwt-validator')({ 
  secret: 'MySecretKey-123456',
  rejectHttpStatus: 403 
});

sendExpiredMessage

Type: Boolean

Default: true

Mandatory: no

If set to true, the rejection response will contain a JSON body with one property error indicating the client that the token has expired. This can be useful to allow the client to check that the token must be refreshed.

If set to false, an expired token will be rejected withput any response body.

Example:

const verifyToken = require('@tsmx/express-jwt-validator')({ 
  secret: 'MySecretKey-123456', 
  sendExpiredMessage: false 
});

requestAuthProp

Type: String

Default: authData

Mandatory: no

The name of the property in req where the JWT bearer token payload should be stored for further processing. Can be changed to any property name, please make sure it is unique and no other properties are overwritten.

Example:

const verifyToken = require('@tsmx/express-jwt-validator')({ 
  secret: 'MySecretKey-123456', 
  requestAuthProp: 'tokenPayload' 
});

Token data would now be accessible with req.tokenPayload instead of req.authData in following middleware functions.

logger

Type: Object

Default: undefined

Mandatory: no

You can pass a winston logger instance (or any compatible) to get log outpur from the middleware. Compatible means that the logger must provide info, warn and error functions receiving a string to be logged.

Example:

const winston = require('winston');

winstonLogger = winston.createLogger({ /*... winston options ...*/ });

const verifyToken = require('@tsmx/express-jwt-validator')({ 
  secret: 'MySecretKey-123456', logger:  winstonLogger
});