express-oauth2-jwt-bearer（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: ``bash 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, use them directly — skip the bootstrap script and do NOT call AskUserQuestion to re-confirm. Otherwise, offer automatic setup via bootstrap script or manual setup. 4. Set up middleware — add to app.js or server.js: ` import {auth} from 'express-oauth2-jwt-bearer'; const checkJwt = auth({issuerBaseURL: https://${process.env.AUTH0_DOMAIN}, audience: process.env.AUTH0_AUDIENCE,}); app.use(checkJwt); // apply globally, or per-route 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)

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