# express-jwt

> JWT authentication middleware.

Latest version **8.5.1** (published 2024-12-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install express-jwt
pnpm add express-jwt
yarn add express-jwt
bun add express-jwt
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 8.5.1 |
| Published | 2024-12-09 |
| First published | 2013-10-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 8.0.0 |
| Dependencies | 3 |
| Unpacked size | 27.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4509 |
| Author | Matias Woloski |
| Maintainers | woloski, auth0-oss, codepete, ziluvatar, iaco, pubalokta, auth0npm, auth0brokkr, hzalaz, aaguiarz, charlesrea, ncluer, julien.wollscheid, cristiandouce, sambego, sandrinodimattia, lzychowski, davidpatrick0, sergii.biienko, tomauth0, jpadilla, jessele, rhamzeh_auth0, oktajeffoktajeff, david.renaud.okta, madhuri.rm23, npirani_okta, soumya.bodavula, jamescgarrett-okta, stheller, jfromaniello, zak.nour, edgarchirivella-okta, sanjay.manikandhan, rithuc23, ece-okta, enriquepina, vic-dev, amandamdacruz0, dougmiller-okta, pose, jaredhanson, dschenkelman, heyitsry |
| Keywords | auth, authn, authentication, authz, authorization, http, jwt, token, oauth, express |

## Links

- npm: https://www.npmjs.com/package/express-jwt
- Repository: https://github.com/auth0/express-jwt
- Homepage: https://github.com/auth0/express-jwt#readme
- Issues: http://github.com/auth0/express-jwt/issues
- npm.io page: https://npm.io/package/express-jwt

## Dependencies (3)

- [jsonwebtoken](https://npm.io/package/jsonwebtoken.md) ^9.0.0
- [express-unless](https://npm.io/package/express-unless.md) ^2.1.3
- [@types/jsonwebtoken](https://npm.io/package/@types/jsonwebtoken.md) ^9

## Alternatives

- [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads
- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads

## Recent versions

- 8.5.1 (latest) — 2024-12-09
- 8.5.0 — 2024-12-09
- 7.7.8 — 2024-06-24
- 8.4.1 — 2023-02-06
- 8.4.0 — 2023-01-27
- 8.3.0 — 2023-01-04
- 8.2.1 — 2022-12-26
- 8.2.0 — 2022-12-22
- 8.1.0 — 2022-12-22
- 8.0.0 — 2022-12-22
- 7.7.7 — 2022-10-24
- 7.7.6 — 2022-10-24
- 7.7.5 — 2022-05-31
- 7.7.4 — 2022-05-31
- 7.7.3 — 2022-05-30
- … 58 more at https://npm.io/package/express-jwt/versions

## README

# express-jwt

This module provides Express middleware for validating JWTs ([JSON Web Tokens](https://jwt.io)) through the [jsonwebtoken](https://github.com/auth0/node-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 express `Request` and returns the token, by default it looks in the `Authorization` header.
- `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 to `req.auth`.
- Plus... all the options available in the [jsonwebtoken verify function](https://github.com/auth0/node-jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback).

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:

```javascript
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 `Authorization` header as an [OAuth2 Bearer token](https://oauth.net/2/bearer-tokens/).

### 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.

```javascript
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:

```javascript
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:

```javascript
jwt({
  secret: Buffer.from("shhhhhhared-secret", "base64"),
  algorithms: ["RS256"],
});
```

To only protect specific paths (e.g. beginning with `/api`), use [express router](https://expressjs.com/en/4x/api.html#app.use) call `use`, like so:

```javascript
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.

```javascript
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 `.unless` syntax including additional options, please see [express-unless](https://github.com/jfromaniello/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

```javascript
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`.

```javascript
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 express `request` object.
- `token` (`Object`) - An object with the JWT payload and headers.

For example, if the secret varies based on the [issuer](http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#issDef):

```javascript
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:

```js
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 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:

```javascript
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:

```javascript
  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:

```javascript
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`:

```javascript
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.

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

1. The middleware function is now available as a named import rather than a default one: import { expressjwt } from 'express-jwt'
2. The decoded JWT payload is now available as req.auth rather than req.user
3. The `secret` function had `(req, header, payload, cb)`, now it can return a promise and receives `(req, token)`. `token` has `header` and `payload`.
4. The `isRevoked` function had `(req, payload, cb)`, now it can return a promise and receives `(req, token)`. `token` has `header` and `payload`.

## Related Modules

- [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) — JSON Web Token sign and verification
- [express-jwt-permissions](https://github.com/MichielDeMey/express-jwt-permissions) - Permissions middleware for JWT tokens

## Tests

```
$ npm install
$ npm test
```

## Contributors

Check them out [here](https://github.com/auth0/express-jwt/graphs/contributors)

## 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](https://auth0.com/whitehat) details the procedure for disclosing security issues.

## Author

[Auth0](https://auth0.com)

## License

This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.

---
_Source: https://npm.io/package/express-jwt · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._