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)
  • .jwt(options)
  • .refreshJwt(refreshToken, oldToken, context)
  • .jwtRole(roleOrRoles)
  • .oauthCompletion(config)

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 |

expressJwtFusionAuth.jwtRole(roleOrRoles)

Kind: instance method of ExpressJwtFusionAuth

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

expressJwtFusionAuth.oauthCompletion(config)

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.