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

Provides factory methods for Express middleware/handlers used to obtain and validate JSON Web Tokens (JWTs).

Kind: global class

• ExpressJwtFusionAuth
  • new ExpressJwtFusionAuth(fusionAuthUrl)
  • .jwt(options)
  • .refreshJwt(refreshToken, oldToken, context)
  • .jwtRole(roleOrRoles)
  • .oauthCompletion(config)

new ExpressJwtFusionAuth(fusionAuthUrl)

Creates a middleware factory that communicates with FusionAuth at the given URL.

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

expressJwtFusionAuth.jwt(options)

Returns a middleware/handler that checks whether a request has a JWT attached, validates the JWT, and associates the JWT contents with the request object. By default, if the client appears to be a web browser, it will be redirected to the FusionAuth OAuth 2.0 login URL. However, this behavior can be enabled or disabled for all clients.

Kind: instance method of ExpressJwtFusionAuth

Param	Type	Description
options	JwtOptions	the JWT acquisition and verification options

expressJwtFusionAuth.refreshJwt(refreshToken, oldToken, context)

Requests and parses/validates a new JWT/access token using a refresh token obtained from a prior OAuth login or JWT refresh. Note that the middleware/handler returned by jwt() will do this automatically for an expired access token if a refresh token is available. This function is provided for cases where an application needs to refresh explicitly, such as when exchanging a FusionAuth JWT for an application-generated JWT.

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

expressJwtFusionAuth.jwtRole(roleOrRoles)

Returns a middleware/handler that checks whether a request has a valid JWT attached that has at least one of the given application roles. The request must have already had the JWT parsed and validated by the ExpressJwtFusionAuth.jwt middleware. If the JWT is not present or does not have one of the required roles, the request is failed with HTTP 403 Forbidden.

Kind: instance method of ExpressJwtFusionAuth

Param	Type	Description
roleOrRoles	string	the role or roles to check for

expressJwtFusionAuth.oauthCompletion(config)

Returns a handler for the OAuth 2.0 redirection endpoint that exchanges an authorization code for a JWT/access token and optional refresh token.

Kind: instance method of ExpressJwtFusionAuth

Param	Type	Description
config	OAuthConfig	the OAuth 2.0 configuration settings

License

express-jwt-fusionauth is available under the ISC license.