express-jwt
Advanced tools
The express-jwt package is a middleware for Express.js that allows you to validate JSON Web Tokens (JWTs) in your HTTP requests. It is commonly used for securing routes and ensuring that only authenticated users can access certain endpoints.
JWT Validation
This feature allows you to validate JWTs in incoming requests. The middleware checks the token's validity and ensures it is signed with the correct secret key and algorithm.
const express = require('express');
const jwt = require('express-jwt');
const app = express();
const jwtMiddleware = jwt({
secret: 'your-secret-key',
algorithms: ['HS256']
});
app.use('/protected', jwtMiddleware, (req, res) => {
res.send('This is a protected route');
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});Error Handling
This feature allows you to handle errors that occur during JWT validation. For example, you can send a 401 Unauthorized response if the token is invalid.
const express = require('express');
const jwt = require('express-jwt');
const app = express();
const jwtMiddleware = jwt({
secret: 'your-secret-key',
algorithms: ['HS256']
});
app.use('/protected', jwtMiddleware, (err, req, res, next) => {
if (err.name === 'UnauthorizedError') {
res.status(401).send('Invalid token');
} else {
next(err);
}
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});Token Decoding
This feature allows you to decode the JWT and attach the payload to the request object. You can then access the decoded information in your route handlers.
const express = require('express');
const jwt = require('express-jwt');
const app = express();
const jwtMiddleware = jwt({
secret: 'your-secret-key',
algorithms: ['HS256'],
requestProperty: 'auth'
});
app.use('/protected', jwtMiddleware, (req, res) => {
res.send(`Hello, ${req.auth.name}`);
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});The jsonwebtoken package is a popular library for creating and verifying JSON Web Tokens. Unlike express-jwt, it does not provide middleware for Express.js, but it offers more flexibility for handling tokens in various contexts.
The passport-jwt package is a Passport.js strategy for authenticating with a JSON Web Token. It integrates with Passport.js, a popular authentication middleware for Node.js, and provides more comprehensive authentication solutions compared to express-jwt.
The koa-jwt package is similar to express-jwt but is designed for Koa.js applications. It provides middleware for validating JWTs in Koa.js, making it a suitable alternative for developers using the Koa framework.
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.
$ npm install express-jwt
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.
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']
});
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, cal 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"] });
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;
},
})
);
If you are developing an application in which the secret used to sign tokens is not static, you can provide a callback function as the secret parameter. The function has the signature: function(req, payload, done):
req (Object) - The express request object.token (Object) - An object with the JWT payload and headers.For example, if the secret varies based on the JWT 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);
}
);
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 express request object.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);
}
);
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,
})
);
An ExpressJwtRequest type is provided which extends express.Request with the auth property.
import { expressjwt, ExpressJwtRequest } from "express-jwt";
app.get(
"/protected",
expressjwt({ secret: "shhhhhhared-secret", algorithms: ["HS256"] }),
function (req: ExpressJwtRequest, res: express.Response) {
if (!req.auth.admin) return res.sendStatus(401);
res.sendStatus(200);
}
);
$ npm install
$ npm test
Check them out here
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.
This project is licensed under the MIT license. See the LICENSE file for more info.
7.4.2 - 2022-04-20
FAQs
JWT authentication middleware.
The npm package express-jwt receives a total of 330,699 weekly downloads. As such, express-jwt popularity was classified as popular.
We found that express-jwt demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 48 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.