Express-jwt-fusionauth NPM

express-jwt-fusionauth

Express middleware for JSON Web Token (JWT)-based authentication against FusionAuth. It provides these main functions:

Find, parse, and verify a JWT, and attach its claims to the Express request, optionally requiring that it be present.\ As a convenience for browser-based API testing, the client can be optionally redirected to a login page when the required JWT is missing or invalid.
Automatically refresh an expired JWT token if a refresh token cookie is available.
Check that the JWT has at least one of a set of application-defined roles.
Implement the redirection endpoint that exchanges an OAuth authorization code for a JWT.
In addition to obtaining and verifying a JWT from FusionAuth, the middlware can also issue and verify application-defined JWTs. This allows application-specific claims to be included.

While most of the mechanics of JWT (RFC 7519) and OAuth 2.0 (RFC 6749) are standard across identity providers, this implementation focuses on specifics of FusionAuth and its best practices to make integration as safe and simple as possible. For example, the TypeScript definition of the JWT claims interface contains only the subset of registered claims used by FusionAuth, as well as the private claims it adds.

Installation

npm install express-jwt-fusionauth

Sample Usage

import bodyParser from 'body-parser';
import cookieParser from 'cookie-parser';
import express from 'express';
import { ExpressJwtFusionAuth } from 'express-jwt-fusionauth';

// environment-specific settings and secrets
const { FUSIONAUTH_URL = 'http://fusionauth:9011' } = process.env;
const { JWT_ISSUER = 'acme.com' } = process.env;
const { OAUTH_CLIENT_ID = '31d7b8e8-f67e-4fb0-9c0b-872b793cda7a' } = process.env;
const { OAUTH_CLIENT_SECRET = 'VYKsyjndsJ7lTnS2Z5vuz4SM-8Dvy1-4_yvqEoALMfY' } = process.env;
const { OAUTH_REDIRECT_URI = 'http://localhost:3000/oauth' } = process.env;
const { OAUTH_COOKIE_DOMAIN = 'localhost' } = process.env;

const oauthConfig = {
  clientId: OAUTH_CLIENT_ID,
  clientSecret: OAUTH_CLIENT_SECRET,
  redirectUri: OAUTH_REDIRECT_URI,
  cookieConfig: {
    domain: OAUTH_COOKIE_DOMAIN
  }
};

const jwtOptions = {
  oauthConfig,
  required: true,
  alwaysLogin: false,
  browserLogin: true,
  verifyOptions: {
    issuer: JWT_ISSUER,
    audience: OAUTH_CLIENT_ID
  }
};

// create the middleware/handler factory
const auth = new ExpressJwtFusionAuth(FUSIONAUTH_URL);

const app = express();

// add the cookie-parser middleware to extract JWTs from the access_token cookie
app.use(cookieParser());

// add a route corresponding to the OAuth redirect URI,
// used to exchange an authorization code for a JWT/access token
app.get('/oauth', auth.oauthCompletion(oauthConfig));
app.post('/oauth', bodyParser.urlencoded({ extended: true }), auth.oauthCompletion(oauthConfig));

// sample route requiring JWT authentication and the "root" or "admin" application role;
// for demonstration purposes, it just dumps the JWT claims as JSON
app.get('/authed',
  auth.jwt(jwtOptions),
  auth.jwtRole(['root', 'admin']),
  (req: express.Request, res) => res.json(req.jwt!));

// sample route with optional JWT authentication
app.get('/opt-authed',
  auth.jwt({ ...jwtOptions, required: false }),
  (req: express.Request, res) => res.send(req.jwt ? req.jwt.email : 'nobody'));

app.listen();

API Reference

ExpressJwtFusionAuth

Kind: global class

ExpressJwtFusionAuth

new ExpressJwtFusionAuth(fusionAuthUrl)

Param	Type	Description
fusionAuthUrl	string	the base URL of the FusionAuth application (e.g. http://fusionauth:9011)

expressJwtFusionAuth.jwt(options)

Kind: instance method of ExpressJwtFusionAuth

Param	Type	Description
options	JwtOptions	the JWT acquisition and verification options

expressJwtFusionAuth.refreshJwt(refreshToken, oldToken, context)

Kind: instance method of ExpressJwtFusionAuth

Param	Description
refreshToken	the refresh token from the prior login or refresh
oldToken	the original, expired access token (for JWT Refresh webhook event)
context	the refresh context, optionally containing JWT transform options and Express request/response