express-oauth2-jwt-bearer

Node OAuth2 JWT Bearer Integration

The express-oauth2-jwt-bearer package provides Express middleware for validating Auth0 JWT Bearer access tokens. It handles token extraction, signature verification, audience and issuer validation, and expiry checks per RFC 6750 — letting you focus on business logic rather than JWT parsing.

Agent instruction: Before providing SDK setup instructions, fetch the latest release version by running:

gh api repos/auth0/node-oauth2-jwt-bearer/releases/latest --jq '.tag_name'

Use the returned version in all package.json dependency lines instead of any hardcoded version below.

Prerequisites

• Node.js 18+ (20+ recommended; required for bootstrap script automation)
• Express 4.x or 5.x
• npm or yarn
• An Auth0 account with a configured API (Resource Server)
• Auth0 CLI (for automatic setup): npm install -g @auth0/auth0-cli

When NOT to Use

Quick Start Workflow

Agent instruction: Follow these steps to integrate express-oauth2-jwt-bearer into the user's Node.js API project.

1. Fetch latest version (see instruction above).

2. Install the SDK:

   npm install express-oauth2-jwt-bearer

3. Configure Auth0 — follow references/setup.md. If the user already provided their Auth0 Domain and API Audience in the prompt, write them to a .env file as ISSUER_BASE_URL (the full issuer URL, including https://) and AUDIENCE — the SDK reads these automatically. Skip the bootstrap script and do NOT call AskUserQuestion to re-confirm. Never hardcode the domain or audience as literal strings (or || fallback defaults) in server.js / app.js — they belong in .env only. Otherwise, offer automatic setup via bootstrap script or manual setup.

4. Set up middleware — first create a .env file with the Auth0 values, then load it and add the middleware. express-oauth2-jwt-bearer reads ISSUER_BASE_URL and AUDIENCE from the environment automatically, so auth() needs no arguments:

   # .env
   ISSUER_BASE_URL=https://your-tenant.us.auth0.com
   AUDIENCE=https://your-api-identifier

   import 'dotenv/config'; // load .env before the SDK reads process.env
   import { auth } from 'express-oauth2-jwt-bearer';
    
   // Reads ISSUER_BASE_URL and AUDIENCE from the environment — no config needed
   const checkJwt = auth();
    
   app.use(checkJwt); // apply globally, or per-route

   Keep the issuer and audience in .env — do not inline literal values or pass them as arguments here.

5. Protect endpoints — apply middleware globally or to specific routes:

   // Global protection
   app.use(checkJwt);
    
   // Or per-route
   app.get('/api/private', checkJwt, (req, res) => {
     res.json({ sub: req.auth.payload.sub });
   });

6. Add RBAC (optional) — use requiredScopes() or claimIncludes() for permission-based access:

   import { auth, requiredScopes, claimIncludes } from 'express-oauth2-jwt-bearer';
    
   app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => {
     res.json({ messages: [] });
   });

   Important: requiredScopes accepts a single argument — a space-separated string or an array. Do NOT pass multiple string arguments: requiredScopes('read:msg', 'write:msg') silently ignores everything after the first. Use requiredScopes('read:msg write:msg') or requiredScopes(['read:msg', 'write:msg']) instead.

7. Verify the integration — build and test:

   node server.js
   curl http://localhost:3000/api/private         # should return 401
   curl -H "Authorization: Bearer <token>" http://localhost:3000/api/private  # should return 200

8. Failcheck: If the server fails to start or tokens are rejected unexpectedly, check references/api.md for common issues. After 5-6 failed iterations, use AskUserQuestion to ask the user for more details about their environment.

Detailed Documentation

• Setup Guide — Auth0 API registration, .env configuration, bootstrap script for automated setup, and secret management
• Integration Patterns — Protected endpoints, RBAC with scopes and claims, DPoP, CORS setup, error handling, and testing with curl
• API Reference & Testing — Full configuration options, claims reference, complete code example, testing checklist, and common issues

Common Mistakes

Related Skills

• auth0-express — For Express web apps with login UI (sessions, cookies)
• auth0-nextjs — For Next.js server-side web apps
• auth0-aspnetcore-api — BACKEND_API reference implementation for .NET
• go-jwt-middleware — JWT middleware for Go APIs
• auth0-api-python — JWT validation for Python APIs (Flask/FastAPI)
• auth0-cli — Manage Auth0 resources from the terminal

Quick Reference

Core Middleware

Configuration Options

Environment Variables

Request Object

After successful validation, req.auth contains:

req.auth.payload    // Decoded JWT payload (sub, iss, aud, exp, permissions, etc.)
req.auth.header     // JWT header (alg, typ, kid)
req.auth.token      // Raw JWT string

SDK Architecture

The node-oauth2-jwt-bearer monorepo contains three packages:

In practice, you only install and import express-oauth2-jwt-bearer.

Auth Flow Comparison

Testing Quick Reference

# Get test token from Auth0 Dashboard → APIs → your API → Test tab
# Copy the token, then:
 
# 1. Verify 401 on protected route (no token)
curl -v http://localhost:3000/api/private
 
# 2. Verify 200 with valid token
curl -H "Authorization: Bearer <paste-token-here>" http://localhost:3000/api/private
 
# 3. Verify 403 with valid token but missing scope
curl -H "Authorization: Bearer <paste-token-here>" http://localhost:3000/api/admin
 
# 4. Verify CORS preflight
curl -v -X OPTIONS http://localhost:3000/api/private \
  -H "Origin: http://localhost:5173" \
  -H "Access-Control-Request-Method: GET" \
  -H "Access-Control-Request-Headers: Authorization"

References

• express-oauth2-jwt-bearer on npm
• GitHub: auth0/node-oauth2-jwt-bearer
• Auth0 Node.js API Quickstart
• Auth0 APIs Dashboard
• RFC 6750 — Bearer Token Usage