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

``sh
npm install express-jwt-fusionauth
`

Sample Usage

`ts
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

$3

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