Registry / auth-security / express-oauth2-jwt-bearer

express-oauth2-jwt-bearer

library1.8.0jsnpmunverified

Authentication middleware for Express.js that validates JWT Bearer access tokens issued by an OAuth 2.0 authorization server. Version 1.8.0 supports DPoP (Proof-of-Possession) authentication, multiple custom domains, clock tolerance for nbf claim, and Node.js versions 12 through 24. Maintained by Auth0 with 100% test coverage. Differentiates from other JWT middleware by being Auth0-optimized, supporting OAuth 2.0 token validation (not just JWT decoding), and providing built-in security headers guidance.

auth-security web-framework

npm install express-oauth2-jwt-bearer

github ↗package ↗

INSTALL

IMPORT

SIG · EXPRESS-OAUTH2-JWT

express-oauth2-jwt-bearer

auth-securityjavascriptv1.8.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

auth

✓ import { auth } from 'express-oauth2-jwt-bearer'

✗ const auth = require('express-oauth2-jwt-bearer')

ESM is fully supported. In CommonJS, use const { auth } = require('express-oauth2-jwt-bearer').

VerificationError

✓ import { VerificationError } from 'express-oauth2-jwt-bearer'

✗ import { UnauthorizedError } from 'express-oauth2-jwt-bearer'

The error type is VerificationError, not UnauthorizedError. Use err.status and err.headers for RFC 6750 compliance.

ClaimCheckError

✓ import { ClaimCheckError } from 'express-oauth2-jwt-bearer'

✗ import { CheckError } from 'express-oauth2-jwt-bearer'

Thrown when custom claim checks fail. Always use err.status to determine HTTP response code.

Shows how to configure auth middleware, protect a route with scopes, and access the decoded token payload.

import { auth, requiredScopes } from 'express-oauth2-jwt-bearer'; import express from 'express'; const app = express(); // Validate JWT bearer token app.use( auth({ issuerBaseURL: process.env.ISSUER_BASE_URL ?? 'https://example.auth0.com', audience: process.env.AUDIENCE ?? 'https://api.example.com', }) ); // Protected route app.get('/api/messages', requiredScopes('read:messages'), (req, res) => { res.json({ message: 'Access granted', payload: req.auth.payload, }); }); // Error handling (Express default handles err.status and err.headers) const port = process.env.PORT ?? 3000; app.listen(port, () => console.log(`Server running on port ${port}`));

Debug

Known issues

breakingIn v1.7.3, the unauthorized response status code changed from 401 to 403 for insufficient scope errors, as per RFC 6750.

fix

Update to v1.7.3 or later. If you relied on the previous 401 status, adjust your error handling logic.

affects: >=1.7.0 <1.7.3

gotchaThe library silently changes 401 to 403 in some error conditions; always use err.status from the error object, not a hardcoded value.

fix

In error handling middleware, use err.status (e.g., if (err.status === 403) {...}) instead of assuming 401.

affects: >=1.0.0

deprecatedThe 'secret' option (for symmetric algorithms like HS256) is deprecated since v1.4.0 and discouraged for production; use asymmetric keys (RS256) via issuerBaseURL.

fix

Use issuerBaseURL with a JWKS endpoint instead of secret. If you must use HS256, ensure secret is a strong symmetric key.

affects: >=1.4.0

gotchaWhen using issuer (not issuerBaseURL) for symmetric algorithms, you must also specify tokenSigningAlg: 'HS256'. Omitting it defaults to RS256 which will fail.

fix

Specify tokenSigningAlg: 'HS256' when using symmetric secret. Example: auth({ issuer: '...', audience: '...', secret: '...', tokenSigningAlg: 'HS256' })

affects: >=1.0.0

gotchaDPoP authentication is in early access; the default mode accepts both DPoP and Bearer tokens. To enforce DPoP-only, you must set dpop: { enforce: true }.

fix

Read EXAMPLES.md for full DPoP config options. Set dpop: { enforce: true } to require DPoP proof.

affects: >=1.7.0

Errors

Common errors & fixes

express-oauth2-jwt-bearer: UnauthorizedError: jwt issuer is not configured

Missing issuerBaseURL or issuer option in auth() config.

fix

Add issuerBaseURL to auth(): auth({ issuerBaseURL: 'https://your-tenant.auth0.com/', audience: '...' })

TypeError: Cannot destructure property 'auth' of (intermediate value) as it is undefined

Incorrect import: using default import instead of named import.

fix

Use named import: import { auth } from 'express-oauth2-jwt-bearer' (or const { auth } = require(...) for CJS)

jwks-rsa: Error: unable to get local issuer certificate

HTTPS TLS certificate validation failed, often due to self-signed certs or corporate proxies.

fix

Set NODE_TLS_REJECT_UNAUTHORIZED=0 (only for development) or configure proper CA certificates.

Upgrade

Version history

1.8.0latest on npm

Audit

Dependencies

expressrequiredPeer dependency for Express.js middleware integration

jwks-rsarequiredRetrieves RSA public keys from JWKS endpoint for token signature verification

jsonwebtokenrequiredUsed for JWT decoding and verification under the hood

Agent activity

14 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/auth0/node-oauth2-jwt-bearer ↗

packagehttps://www.npmjs.com/package/express-oauth2-jwt-bearer ↗