表达承载
- 作者仓库星标 0
- 许可证 Apache-2.0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · Apache-2.0
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 需要 · Vendor-specific
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js · Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
> npm install 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
| Use Case | Recommended Skill |
|----------|------------------|
| Building a server-side web app with login UI (Express sessions) | `auth0-express` |
| Building a Next.js app with server-side auth | `auth0-nextjs` |
| Building a React/Angular/Vue SPA | `auth0-react`, `auth0-angular`, `auth0-vue` |
| Building a React Native or mobile app | `auth0-react-native`, `auth0-android`, `auth0-swift` |
| ASP.NET Core Web API | `auth0-aspnetcore-api` |
| Go API with JWT middleware | `go-jwt-middleware` |
| Python API (Flask/FastAPI) | `auth0-api-python` |
| Node.js API using the older `express-jwt` package | `express-jwt` |
## 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:**
> ```bash
> 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`:
> ```javascript
> 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:
> ```javascript
> // 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:
> ```javascript
> 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:
> ```bash
> 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](./references/setup.md)** — Auth0 API registration, .env configuration, bootstrap script for automated setup, and secret management
- **[Integration Patterns](./references/integration.md)** — Protected endpoints, RBAC with scopes and claims, DPoP, CORS setup, error handling, and testing with curl
- **[API Reference & Testing](./references/api.md)** — Full configuration options, claims reference, complete code example, testing checklist, and common issues
## Common Mistakes
| Mistake | Symptom | Fix |
|---------|---------|-----|
| Created an **Application** instead of an **API** in Auth0 Dashboard | Token validation fails; wrong audience | Create a new **API** (Resource Server) in Auth0 Dashboard → APIs |
| Audience doesn't match API identifier exactly | `401 Unauthorized` — "Audience mismatch" | Copy the exact API Identifier string from Auth0 Dashboard → APIs |
| Domain includes `https://` prefix | `Error: Invalid URL` at startup | Use hostname only: `your-tenant.us.auth0.com`, not `https://...` |
| Checking `scope` claim instead of `permissions` for RBAC | 403 always returned or permissions ignored | Use `requiredScopes()` for scope-based RBAC; use `claimIncludes('permissions', 'read:data')` for Auth0 RBAC permission claims |
| CORS not configured before auth middleware | Preflight OPTIONS requests return 401 | Add `cors()` middleware before `auth()` in the middleware chain |
| `.env` file not loaded | `undefined` for domain/audience | Add `import 'dotenv/config'` at the top of the entry file |
| `req.auth` is undefined | `TypeError: Cannot read properties of undefined` | Verify `checkJwt` middleware runs before the handler |
## Related Skills
- **[auth0-express](../auth0-express)** — For Express web apps with login UI (sessions, cookies)
- **[auth0-nextjs](../auth0-nextjs)** — For Next.js server-side web apps
- **[auth0-aspnetcore-api](../auth0-aspnetcore-api)** — BACKEND_API reference implementation for .NET
- **[go-jwt-middleware](../go-jwt-middleware)** — JWT middleware for Go APIs
- **[auth0-api-python](../auth0-api-python)** — JWT validation for Python APIs (Flask/FastAPI)
- **[auth0-cli](../auth0-cli)** — Manage Auth0 resources from the terminal
## Quick Reference
### Core Middleware
| Function | Description | Returns |
|----------|-------------|---------|
| `auth(options?)` | JWT Bearer validation middleware | `Handler` — 401 if token invalid/missing |
| `requiredScopes(scopes)` | Validates token has all required scopes | `Handler` — 403 if scopes missing |
| `scopeIncludesAny(scopes)` | Validates token has at least one scope | `Handler` — 403 if no match |
| `claimEquals(claim, value)` | Validates a claim equals a value | `Handler` — 401 if mismatch |
| `claimIncludes(claim, ...values)` | Validates claim includes all values | `Handler` — 401 if incomplete |
| `claimCheck(fn, desc?)` | Custom claim validation function | `Handler` — 401 if fn returns false |
### Configuration Options
| Option | Type | Description |
|--------|------|-------------|
| `issuerBaseURL` | `string` | Auth0 domain with `https://` (required unless using env vars) |
| `audience` | `string` | API Identifier from Auth0 Dashboard (required unless using env vars) |
| `tokenSigningAlg` | `string` | Signing algorithm (default: `RS256`; use `HS256` for symmetric) |
| `authRequired` | `boolean` | Set `false` to make authentication optional (default: `true`) |
| `clockTolerance` | `number` | Clock skew tolerance in seconds (no default; undefined unless set) |
| `dpop` | `DPoPOptions` | DPoP configuration (see integration.md) |
### Environment Variables
| Variable | Description |
|----------|-------------|
| `ISSUER_BASE_URL` | Auth0 domain with `https://` (auto-detected by SDK) |
| `AUDIENCE` | API Identifier (auto-detected by SDK) |
### Request Object
After successful validation, `req.auth` contains:
```typescript
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:
| Package | Purpose |
|---------|---------|
| `express-oauth2-jwt-bearer` | **Main package.** Express middleware for JWT Bearer validation. Published to npm. |
| `access-token-jwt` | Low-level JWT verification utilities (used internally). |
| `oauth2-bearer` | RFC 6750 Bearer token extraction (used internally). |
In practice, you only install and import `express-oauth2-jwt-bearer`.
## Auth Flow Comparison
| Auth Pattern | SDK | When to Use |
|-------------|-----|-------------|
| JWT Bearer (stateless) | `express-oauth2-jwt-bearer` | APIs called by SPAs, mobile apps, M2M clients |
| Session-based (stateful) | `@auth0/express-openid-connect` | Web apps with login UI and server-side sessions |
## Testing Quick Reference
```bash
# 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](https://www.npmjs.com/package/express-oauth2-jwt-bearer)
- [GitHub: auth0/node-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer)
- [Auth0 Node.js API Quickstart](https://auth0.com/docs/quickstart/backend/nodejs/interactive)
- [Auth0 APIs Dashboard](https://manage.auth0.com/#/apis)
- [RFC 6750 — Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750)
---
> Source: [auth0/agent-skills](https://github.com/auth0/agent-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
先决条件
何时不使用
快速启动工作流程
详细文档
常见错误
文件/命令 -> express-oauth2-jwt-bearer · package.json · npm install -g @auth0/auth0-cli · auth0-express · auth0-nextjs · auth0-react · auth0-angular · auth0-vue
内容校验值 -> c0b6e56a9e20
当前原文的自动摘译,尚未人工审校。
先决条件
Node.js 18+(推荐 20+;引导脚本自动化所需) Express 4.x 或 5.x npm 或 yarn 具有配置的 API(资源服务器)的 Auth0 帐户 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快速启动工作流程
代理说明:按照以下步骤将
express-oauth2-jwt-bearer集成到用户的Node.js API项目中。 1. 获取最新版本(参见上面的说明)。 2.安装SDK:```bash npm installexpress-oauth2-jwt-bearer详细文档
设置指南 — Auth0 API 注册、.env 配置、用于自动设置的引导脚本和秘密管理 集成模式 — 受保护的端点、具有范围和声明的 RBAC、DPoP、CORS 设置、错误处理以及使用 curl 进行测试 API 参考和测试 — 完整的配置选项、声明参考、完整的代码示例、测试清单和常见问题
常见错误
错误 · 症状 · 修复 在 Auth0 仪表板中创建应用程序而不是 API · 令牌验证失败;错误的受众 · 在 Auth0 仪表板中创建新的 API(资源服务器) → API 受众与 API 标识符不完全匹配 ·
401 Unauthorized—“受众不匹配” · 从 Auth0 仪表板复制准确的 API 标识符字符串 → API 域包含https://前缀 · 启动时使用Error: Invalid URL· 仅使用主机名:your-tenant.us.auth0.com,不使用https://...