by 运行时依赖
安装命令
点击复制技能文档
Node OAuth2 JWT Bearer 集成 express-oauth2-jwt-bearer 包提供了 Express 中间件用于验证 Auth0 JWT Bearer 访问令牌。它处理令牌提取、签名验证、受众和颁发者验证以及过期检查，按照 RFC 6750 规范 —— 让您专注于业务逻辑而不是 JWT 解析。
代理指令：在提供 SDK 设置说明之前，通过运行以下命令获取最新的发布版本： gh api repos/auth0/node-oauth2-jwt-bearer/releases/latest --jq '.tag_name' 在所有 package.json 依赖项行中使用返回的版本，而不是任何硬编码版本。
前提条件 Node.js 18+（推荐 20+；对于 bootstrap 脚本自动化是必需的） Express 4.x 或 5.x npm 或 yarn Auth0 帐户，配置了 API（资源服务器） Auth0 CLI（用于自动设置）：npm install -g @auth0/auth0-cli
何时不使用 用例 推荐技能 构建具有登录 UI 的服务器端 Web 应用（Express 会话） auth0-express 构建具有服务器端身份验证的 Next.js 应用 auth0-nextjs 构建 React/Angular/Vue SPA auth0-react, auth0-angular, auth0-vue 构建 React Native 或移动应用 auth0-react-native, auth0-android, auth0-swift ASP.NET Core Web API auth0-aspnetcore-api 使用 JWT 中间件的 Go API go-jwt-middleware Python API（Flask/FastAPI） auth0-api-python 使用较旧的 express-jwt 包的 Node.js API express-jwt
快速入门工作流
代理指令：按照以下步骤将 express-oauth2-jwt-bearer 集成到用户的 Node.js API 项目中。
获取最新版本（见上述指令）。
安装 SDK：npm install express-oauth2-jwt-bearer
配置 Auth0 —— 按照 references/setup.md 进行。
如果用户已经在提示中提供了 Auth0 域和 API 受众，则直接使用它们 —— 跳过 bootstrap 脚本并且不要调用 AskUserQuestion 以重新确认。
否则，提供通过 bootstrap 脚本或手动设置进行自动设置。
设置中间件 —— 将其添加到 app.js 或 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); // 全局应用，或每个路由
保护端点 —— 全局应用中间件或应用于特定路由：
// 全局保护
app.use(checkJwt);
// 或每个路由
app.get('/api/private', checkJwt, (req, res) => {
res.json({ sub: req.auth.payload.sub });
});
添加 RBAC（可选）— 使用 requiredScopes() 或 claimIncludes() 进行基于权限的访问：
import { auth, requiredScopes, claimIncludes } from 'express-oauth2-jwt-bearer';
app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => {
res.json({ messages: [] });
});
重要：requiredScopes 接受单个参数 —— 空格分隔的字符串或数组。不要传递多个字符串参数：requiredScopes('read:msg', 'write:msg') 会默默地忽略所有内容，仅保留第一个。
使用 requiredScopes('read:msg write:msg') 或 requiredScopes(['read:msg', 'write:msg']) 代替。
验证集成 —— 构建和测试：
node server.js
curl http://localhost:3000/api/private # 应该返回 401
curl -H "Authorization: Bearer " http://localhost:3000/api/private # 应该返回 200
故障检查：如果服务器无法启动或令牌被意外拒绝，请检查 references/api.md 中的常见问题。
在 5-6 次失败的迭代之后，使用 AskUserQuestion 询问用户有关其环境的更多详细信息。
详细文档 设置指南 —— Auth0 API 注册、.env 配置、bootstrap 脚本用于自动设置和密钥管理 集成模式 —— 受保护的端点、RBAC 与范围和声明、DPoP、CORS 设置、错误处理和使用 curl 进行测试 API 参考和测试 —— 完整的配置选项、声明参考、完整的代码示例、测试清单和常见问题
常见错误 错误 症状 解决方案 在 Auth0 仪表板中创建了应用程序而不是 API 令牌验证失败；错误的受众 在 Auth0 仪表板中创建一个新的 API（资源服务器）→ API 受众不完全匹配 API 标识符 401 未经授权 —— “受众不匹配” 从 Auth0 仪表板中复制 API 标识符的确切字符串 → API 域包含 https:// 前缀 启动时出错：无效 URL 使用主机名：your-tenant.us.auth0.com，而不是 https://... 检查范围声明而不是权限进行 RBAC 总是返回 403 或忽略权限 使用 requiredScopes() 进行基于范围的 RBAC；使用 claimIncludes('permissions', 'read:data') 进行 Auth0 RBAC 权限声明 在 auth 中间件之前未配置 CORS OPTIONS 请求返回 401 在中间件链中将 cors() 中间件添加到 auth() 之前 .env 文件未加载 域/受众为 undefined 在入口文件顶部添加 import 'dotenv/config' req.auth 为 undefined TypeError：无法读取 undefined 的属性 验证 checkJwt 中间件在处理程序之前运行
相关技能 auth0-express —— 适用于具有登录 UI 的 Express Web 应用（会话）