JWT Handling Libraries for Node.js Authentication
express-jwt, jose, jsonwebtoken, jwa, and passport-jwt are npm packages used for handling JSON Web Tokens (JWTs) in Node.js applications. They provide utilities for signing, verifying, and managing JWT-based authentication, but differ significantly in scope, standards compliance, and integration patterns. jsonwebtoken is a general-purpose JWT library, jose offers modern, spec-compliant JWT/JWS/JWE support, jwa provides low-level cryptographic primitives, while express-jwt and passport-jwt are framework-specific middleware layers built on top of other JWT libraries for Express and Passport.js respectively.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
JWT Handling in Node.js: express-jwt vs jose vs jsonwebtoken vs jwa vs passport-jwt
When building secure web applications with JSON Web Tokens (JWTs), choosing the right library is critical—not just for correctness, but for maintainability, standards compliance, and long-term security. The five packages under review—express-jwt, jose, jsonwebtoken, jwa, and passport-jwt—serve overlapping but distinct roles in the JWT ecosystem. Let’s unpack how they differ in practice.
🔑 Core Responsibilities: Token Creation vs Verification vs Middleware
Not all JWT libraries do the same thing. Some focus on signing/verifying tokens, others act as Express middleware, and one integrates tightly with Passport authentication.
jsonwebtoken: The Swiss Army Knife
This is the most widely used general-purpose JWT library. It handles both signing and verifying tokens using symmetric (HMAC) or asymmetric (RSA/ECDSA) algorithms.
// Signing a token
const jwt = require('jsonwebtoken');
const token = jwt.sign({ userId: 123 }, 'secret', { expiresIn: '1h' });
// Verifying a token
const payload = jwt.verify(token, 'secret');
It supports standard claims (exp, nbf, aud, etc.) and custom options like clock tolerance.
jose: Modern, Standards-Compliant, and Flexible
jose implements current IETF standards (RFC 7515–7519, RFC 8037) and supports JWS, JWE, JWT, and JWK. It works in both Node.js and browsers, and offers fine-grained control over cryptographic operations.
// Signing with jose (v4+)
import { SignJWT } from 'jose';
const secret = new TextEncoder().encode('secret');
const token = await new SignJWT({ userId: 123 })
.setProtectedHeader({ alg: 'HS256' })
.setIssuedAt()
.setExpirationTime('1h')
.sign(secret);
// Verifying
import { jwtVerify } from 'jose';
const { payload } = await jwtVerify(token, secret);
Unlike jsonwebtoken, jose requires explicit header declaration and uses modern WebCrypto-style APIs.
jwa: Low-Level Algorithm Wrapper
jwa is a minimal utility that only computes JWA (JSON Web Algorithms) signatures. It doesn’t handle JWT structure, claims validation, or expiration—it just signs and verifies raw payloads.
const jwa = require('jwa');
const hmac = jwa('HS256');
const signature = hmac.sign('header.payload', 'secret');
const isValid = hmac.verify('header.payload', signature, 'secret');
You’d typically use this only if you’re building your own JWT implementation from scratch—which you probably shouldn’t.
express-jwt: Express Middleware for Verification
This package is not a JWT signer. It’s an Express middleware that verifies incoming tokens and attaches the decoded payload to req.user.
const express = require('express');
const jwt = require('express-jwt');
const app = express();
app.use(jwt({ secret: 'secret', algorithms: ['HS256'] }));
app.get('/protected', (req, res) => {
// req.user contains decoded token
res.json({ user: req.user });
});
Note: As of 2023, express-jwt wraps jsonwebtoken internally for verification.
passport-jwt: Passport Strategy for JWT
This is a Passport.js strategy that extracts and verifies JWTs, integrating with Passport’s authentication flow.
const JwtStrategy = require('passport-jwt').Strategy;
const ExtractJwt = require('passport-jwt').ExtractJwt;
passport.use(new JwtStrategy({
jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
secretOrKey: 'secret'
}, (payload, done) => {
// payload is decoded token
User.findById(payload.userId, (err, user) => {
if (err) return done(err, false);
if (user) return done(null, user);
else return done(null, false);
});
}));
It delegates actual verification to jsonwebtoken.
⚙️ Cryptographic Flexibility and Standards Compliance
Algorithm Support
jsonwebtoken: Supports HS256/384/512, RS256/384/512, ES256/384/512, PS256/384/512. Uses Node.jscryptomodule.jose: Full JWA support including EdDSA (Ed25519), and JWE encryption (whichjsonwebtokenlacks entirely).jwa: Only signing/verification primitives—no high-level JWT logic.express-jwt/passport-jwt: Inherit algorithm support fromjsonwebtoken.
Standards Adherence
josestrictly follows latest IETF specs and avoids legacy or non-standard extensions.jsonwebtokenincludes some non-standard features (e.g.,jwt.decode(token, { complete: true })returns header + payload + signature), which can be useful but may encourage anti-patterns.jwais standards-compliant at the algorithm level but doesn’t enforce JWT structure rules.
🛡️ Security Considerations
None Algorithm Vulnerability
Older JWT libraries were vulnerable to the "alg": "none" attack. All current versions of these packages reject none by default unless explicitly allowed.
jsonwebtoken: Throws error ifnoneis used without{ algorithms: ['none'] }.jose: Requires explicit opt-in via{ allowInsecureAlgorithm: true }injwtVerify.express-jwt: Forces you to specifyalgorithmsarray—preventing accidentalnoneacceptance.
// express-jwt forces algorithm whitelist
app.use(jwt({ secret: 'secret', algorithms: ['HS256'] })); // ✅ safe
Secret Management
joseencourages use ofUint8Arraysecrets orKeyObjectinstances, aligning with modern crypto best practices.jsonwebtokenaccepts strings or buffers, which can lead to encoding issues if not handled carefully.
🧩 Integration Patterns
Building a Full Auth Flow
If you need to issue and verify tokens, you’ll likely combine tools:
- Use
jsonwebtokenorjoseto sign tokens during login. - Use
express-jwtorpassport-jwtto protect routes.
Example with jsonwebtoken + express-jwt:
// Login route (issuing token)
app.post('/login', (req, res) => {
const token = jwt.sign({ userId: user.id }, process.env.JWT_SECRET, { expiresIn: '1d' });
res.json({ token });
});
// Protected route (verifying token)
app.use('/api', expressJwt({ secret: process.env.JWT_SECRET, algorithms: ['HS256'] }));
With jose, you’d write your own middleware since no official Express wrapper exists:
async function jwtMiddleware(req, res, next) {
const auth = req.headers.authorization;
if (!auth || !auth.startsWith('Bearer ')) return res.sendStatus(401);
try {
const token = auth.substring(7);
const secret = new TextEncoder().encode(process.env.JWT_SECRET);
const { payload } = await jwtVerify(token, secret);
req.user = payload;
next();
} catch (err) {
res.sendStatus(401);
}
}
When to Avoid Certain Packages
- Don’t use
jwaalone for JWT handling—it’s too low-level and error-prone. - Avoid
express-jwtif you’re not using Express—it’s framework-specific. - Don’t use
passport-jwtunless you’re already using Passport.js—it adds unnecessary complexity otherwise.
📦 Maintenance and Future-Proofing
joseis actively maintained, supports modern JavaScript (ESM, TypeScript), and aligns with web platform standards. It’s the best choice for new projects requiring strong standards compliance.jsonwebtokenremains stable and widely used, but development has slowed. Still safe for most use cases.express-jwtandpassport-jwtare wrapper libraries—their health depends onjsonwebtoken. Both are maintained but offer no advantage if you don’t need their specific integration.jwais stable but niche; unlikely to see major updates.
🆚 Summary Table
| Package | Primary Role | Signs Tokens? | Verifies Tokens? | Framework Integration | Standards Compliance |
|---|---|---|---|---|---|
jsonwebtoken | General-purpose JWT utility | ✅ | ✅ | None | Good (with quirks) |
jose | Modern, spec-compliant JWT/JWS/JWE | ✅ | ✅ | None | Excellent |
jwa | Low-level JWA algorithm helper | ✅ (raw) | ✅ (raw) | None | Algorithm-level only |
express-jwt | Express middleware for JWT | ❌ | ✅ (via jsonwebtoken) | Express only | Inherits from jsonwebtoken |
passport-jwt | Passport strategy for JWT | ❌ | ✅ (via jsonwebtoken) | Passport.js only | Inherits from jsonwebtoken |
💡 Final Guidance
- For new greenfield projects: Start with
jose—it’s future-proof, secure by default, and works everywhere. - For existing Express apps using simple HMAC tokens:
jsonwebtoken+express-jwtis battle-tested and sufficient. - If you’re already using Passport.js:
passport-jwtintegrates cleanly. - Avoid
jwaunless you’re implementing a custom JWT parser.
Remember: JWT libraries are security-critical dependencies. Always pin versions, audit regularly, and prefer libraries that enforce safe defaults over those that offer “convenience” at the cost of correctness.
How to Choose: express-jwt vs jose vs jsonwebtoken vs jwa vs passport-jwt
- express-jwt:
Choose
express-jwtif you're building an Express application and need a simple, ready-made middleware to verify JWTs from incoming requests. It automatically decodes tokens and attaches payloads toreq.user, but relies onjsonwebtokenunder the hood—so you still need to manage secrets and algorithms carefully. Avoid it if you're not using Express or need advanced JWT features like encryption. - jose:
Choose
josefor new projects where standards compliance, security, and future-proofing matter most. It fully implements current IETF JWT, JWS, and JWE specifications, supports modern cryptographic algorithms (including EdDSA), and works in both Node.js and browsers. Its API is more verbose but enforces safe practices. Ideal when you need encryption (JWE) or want to avoid legacy design choices found in older libraries. - jsonwebtoken:
Choose
jsonwebtokenif you need a battle-tested, straightforward library for signing and verifying basic JWTs with HMAC or RSA signatures. It’s widely adopted and integrates easily with many frameworks, but lacks support for JWE encryption and includes some non-standard features that can encourage anti-patterns. Still a solid choice for simple authentication flows in existing systems. - jwa:
Choose
jwaonly if you're implementing a custom JWT parser or need direct access to JWA signing/verification primitives without higher-level abstractions. It handles cryptographic operations but doesn't manage JWT structure, claims validation, or expiration logic. For almost all real-world applications, higher-level libraries likejsonwebtokenorjoseare safer and more productive choices. - passport-jwt:
Choose
passport-jwtif your application already uses Passport.js for authentication and you want to add JWT support within Passport's strategy-based architecture. It handles token extraction and verification (viajsonwebtoken) and integrates with Passport's user serialization flow. Don't use it if you're not committed to Passport.js—it adds unnecessary complexity otherwise.
Popular Comparisons
README for express-jwt
express-jwt
This module provides Express middleware for validating JWTs (JSON Web Tokens) through the jsonwebtoken module. The decoded JWT payload is available on the request object.
Install
$ npm install express-jwt
API
expressjwt(options)
Options has the following parameters:
secret: jwt.Secret | GetVerificationKey(required): The secret as a string or a function to retrieve the secret.getToken?: TokenGetter(optional): A function that receives the expressRequestand returns the token, by default it looks in theAuthorizationheader.isRevoked?: IsRevoked(optional): A function to verify if a token is revoked.onExpired?: ExpirationHandler(optional): A function to handle expired tokens.credentialsRequired?: boolean(optional): If its false, continue to the next middleware if the request does not contain a token instead of failing, defaults to true.requestProperty?: string(optional): Name of the property in the request object where the payload is set. Default toreq.auth.- Plus... all the options available in the jsonwebtoken verify function.
The available functions have the following interface:
GetVerificationKey = (req: express.Request, token: jwt.Jwt | undefined) => Promise<jwt.Secret>;IsRevoked = (req: express.Request, token: jwt.Jwt | undefined) => Promise<boolean>;TokenGetter = (req: express.Request) => string | Promise<string> | undefined;
Usage
Basic usage using an HS256 secret:
var { expressjwt: jwt } = require("express-jwt");
// or ES6
// import { expressjwt, ExpressJwtRequest } from "express-jwt";
app.get(
"/protected",
jwt({ secret: "shhhhhhared-secret", algorithms: ["HS256"] }),
function (req, res) {
if (!req.auth.admin) return res.sendStatus(401);
res.sendStatus(200);
}
);
The decoded JWT payload is available on the request via the auth property.
The default behavior of the module is to extract the JWT from the
Authorizationheader as an OAuth2 Bearer token.
Required Parameters
The algorithms parameter is required to prevent potential downgrade attacks when providing third party libraries as secrets.
:warning: Do not mix symmetric and asymmetric (ie HS256/RS256) algorithms: Mixing algorithms without further validation can potentially result in downgrade vulnerabilities.
jwt({
secret: "shhhhhhared-secret",
algorithms: ["HS256"],
//algorithms: ['RS256']
});
Additional Options
You can specify audience and/or issuer as well, which is highly recommended for security purposes:
jwt({
secret: "shhhhhhared-secret",
audience: "http://myapi/protected",
issuer: "http://issuer",
algorithms: ["HS256"],
});
If the JWT has an expiration (
exp), it will be checked.
If you are using a base64 URL-encoded secret, pass a Buffer with base64 encoding as the secret instead of a string:
jwt({
secret: Buffer.from("shhhhhhared-secret", "base64"),
algorithms: ["RS256"],
});
To only protect specific paths (e.g. beginning with /api), use express router call use, like so:
app.use("/api", jwt({ secret: "shhhhhhared-secret", algorithms: ["HS256"] }));
Or, the other way around, if you want to make some paths unprotected, call unless like so.
app.use(
jwt({
secret: "shhhhhhared-secret",
algorithms: ["HS256"],
}).unless({ path: ["/token"] })
);
This is especially useful when applying to multiple routes. In the example above, path can be a string, a regexp, or an array of any of those.
For more details on the
.unlesssyntax including additional options, please see express-unless.
This module also support tokens signed with public/private key pairs. Instead of a secret, you can specify a Buffer with the public key
var publicKey = fs.readFileSync("/path/to/public.pub");
jwt({ secret: publicKey, algorithms: ["RS256"] });
Customizing Token Location
A custom function for extracting the token from a request can be specified with
the getToken option. This is useful if you need to pass the token through a
query parameter or a cookie. You can throw an error in this function and it will
be handled by express-jwt.
app.use(
jwt({
secret: "hello world !",
algorithms: ["HS256"],
credentialsRequired: false,
getToken: function fromHeaderOrQuerystring(req) {
if (
req.headers.authorization &&
req.headers.authorization.split(" ")[0] === "Bearer"
) {
return req.headers.authorization.split(" ")[1];
} else if (req.query && req.query.token) {
return req.query.token;
}
return null;
},
})
);
Retrieve key dynamically
If you need to obtain the key dynamically from other sources, you can pass a function in the secret parameter with the following parameters:
req(Object) - The expressrequestobject.token(Object) - An object with the JWT payload and headers.
For example, if the secret varies based on the issuer:
var jwt = require("express-jwt");
var data = require("./data");
var utilities = require("./utilities");
var getSecret = async function (req, token) {
const issuer = token.payload.iss;
const tenant = await data.getTenantByIdentifier(issuer);
if (!tenant) {
throw new Error("missing_secret");
}
return utilities.decrypt(tenant.secret);
};
app.get(
"/protected",
jwt({ secret: getSecret, algorithms: ["HS256"] }),
function (req, res) {
if (!req.auth.admin) return res.sendStatus(401);
res.sendStatus(200);
}
);
Secret rotation
The getSecret callback could also be used in cases where the same issuer might issue tokens with different keys at certain point:
var getSecret = async function (req, token) {
const { iss } = token.payload;
const { kid } = token.header;
// get the verification key by a given key-id and issuer.
return verificationKey;
};
Revoked tokens
It is possible that some tokens will need to be revoked so they cannot be used any longer. You can provide a function as the isRevoked option. The signature of the function is function(req, payload, done):
req(Object) - The expressrequestobject.token(Object) - An object with the JWT payload and headers.
For example, if the (iss, jti) claim pair is used to identify a JWT:
const jwt = require("express-jwt");
const data = require("./data");
const isRevokedCallback = async (req, token) => {
const issuer = token.payload.iss;
const tokenId = token.payload.jti;
const token = await data.getRevokedToken(issuer, tokenId);
return token !== "undefined";
};
app.get(
"/protected",
jwt({
secret: "shhhhhhared-secret",
algorithms: ["HS256"],
isRevoked: isRevokedCallback,
}),
function (req, res) {
if (!req.auth.admin) return res.sendStatus(401);
res.sendStatus(200);
}
);
Handling expired tokens
You can handle expired tokens as follows:
jwt({
secret: "shhhhhhared-secret",
algorithms: ["HS256"],
onExpired: async (req, err) => {
if (new Date() - err.inner.expiredAt < 5000) { return;}
throw err;
},,
})
Error handling
The default behavior is to throw an error when the token is invalid, so you can add your custom logic to manage unauthorized access as follows:
app.use(function (err, req, res, next) {
if (err.name === "UnauthorizedError") {
res.status(401).send("invalid token...");
} else {
next(err);
}
});
You might want to use this module to identify registered users while still providing access to unregistered users. You can do this by using the option credentialsRequired:
app.use(
jwt({
secret: "hello world !",
algorithms: ["HS256"],
credentialsRequired: false,
})
);
Typescript
A Request type is provided from express-jwt, which extends express.Request with the auth property. It could be aliased, like how JWTRequest is below.
import { expressjwt, Request as JWTRequest } from "express-jwt";
app.get(
"/protected",
expressjwt({ secret: "shhhhhhared-secret", algorithms: ["HS256"] }),
function (req: JWTRequest, res: express.Response) {
if (!req.auth?.admin) return res.sendStatus(401);
res.sendStatus(200);
}
);
Migration from v6
- The middleware function is now available as a named import rather than a default one: import { expressjwt } from 'express-jwt'
- The decoded JWT payload is now available as req.auth rather than req.user
- The
secretfunction had(req, header, payload, cb), now it can return a promise and receives(req, token).tokenhasheaderandpayload. - The
isRevokedfunction had(req, payload, cb), now it can return a promise and receives(req, token).tokenhasheaderandpayload.
Related Modules
- jsonwebtoken — JSON Web Token sign and verification
- express-jwt-permissions - Permissions middleware for JWT tokens
Tests
$ npm install
$ npm test
Contributors
Check them out here
Issue Reporting
If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
Author
License
This project is licensed under the MIT license. See the LICENSE file for more info.