auth0-fastapi-api

Auth0 FastAPI API 集成

使用 auth0-fastapi-api 通过 JWT 访问令牌验证来保护 FastAPI API 端点。

**注意：**此 SDK 目前处于测试阶段。稳定版 1.0 发布前，API 可能会发生变化。请查看 PyPI 获取最新版本。需要 Python >= 3.9 和 FastAPI >= 0.115.11。

---

前置条件

• FastAPI 应用（Python 3.9+）
• 已配置 Auth0 API 资源（不是 Application — 必须是 API）
• 如果尚未设置 Auth0，请先使用 auth0-quickstart 技能

不适用场景

• 服务端渲染的 Web 应用 — 请改用基于会话的登录/注销流程
• 单页应用 — 请使用 auth0-react、auth0-vue 或 auth0-angular 进行客户端身份验证
• 移动应用 — 请使用 auth0-react-native 或 auth0-android
• 颁发令牌 — 此技能用于验证访问令牌，而非颁发令牌

---

快速入门工作流

1. 安装 SDK

pip install auth0-fastapi-api python-dotenv

2. 创建 Auth0 API

你需要在 Auth0 中创建一个 API（而非 Application）。

停止 — 继续之前先询问用户。

请原样提出以下问题，并等待用户回答后再进行其他操作：

"你希望如何创建 Auth0 API 资源？

1. 自动 — 我会运行 Auth0 CLI 脚本来创建资源，并自动将确切的值写入 .env。
2. 手动 — 你在 Auth0 Dashboard 中自行创建 API（或通过 auth0 apis create 创建），并向我提供 Domain 和 Audience。

你更倾向哪种方式？（1 = 自动 / 2 = 手动）"

用户回答之前，不要继续任何设置步骤。不要默认选择手动方式。

如果用户选择自动方式，请按照设置指南运行完整的 CLI 脚本。自动流程会为你写入 .env — 跳过下面的第 3 步，直接进入第 4 步。

如果用户选择手动方式，请按照设置指南中的“手动设置”部分完成全部说明。然后继续下面的第 3 步。

手动创建 API 的快速参考：

# Using Auth0 CLI
auth0 apis create \
  --name "My FastAPI API" \
  --identifier https://my-api.example.com

或者在 Auth0 Dashboard → Applications → APIs 中手动创建

3. 配置环境

创建 .env：

AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_AUDIENCE=https://your-api.example.com

AUTH0_DOMAIN 是你的 Auth0 租户域名（不含 https://）。AUTH0_AUDIENCE 是你在 Auth0 中创建 API 资源时设置的 API 标识符。

4. 初始化 Auth0

import os
from fastapi import FastAPI, Depends
from fastapi_plugin import Auth0FastAPI
from dotenv import load_dotenv

load_dotenv()

app = FastAPI()

auth0 = Auth0FastAPI(
    domain=os.getenv("AUTH0_DOMAIN"),
    audience=os.getenv("AUTH0_AUDIENCE"),
)

每个应用创建一个 Auth0FastAPI 实例，并在各个路由间复用。切勿将域名或 audience 硬编码 — 始终使用环境变量。

5. 保护路由

# Require any valid access token
@app.get("/api/private")
async def private(claims: dict = Depends(auth0.require_auth())):
    return {"user": claims["sub"]}

# No authentication required
@app.get("/api/public")
async def public():
    return {"message": "Public endpoint"}

require_auth() 依赖项会验证 Bearer 令牌、校验签发者和受众，并返回解码后的 JWT 声明。

错误响应：

• 400 invalid_request — Authorization 标头缺失或格式错误
• 401 invalid_token — 令牌已过期、签名无效、签发者/受众不匹配
• 403 insufficient_scope — 令牌有效，但缺少所需的作用域
• 500 internal_server_error — 意外错误

响应正文格式：{"detail": {"error": "...", "error_description": "..."}}

6. 使用作用域检查保护路由

# Requires the read:messages scope
@app.get("/api/messages")
async def get_messages(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
    return {"messages": []}

# Requires both read:data and write:data scopes
@app.post("/api/data")
async def write_data(claims: dict = Depends(auth0.require_auth(scopes=["read:data", "write:data"]))):
    return {"created": True}

require_auth(scopes=...) 会检查 JWT 中的 scope 声明。必须具备所有指定的作用域（AND 逻辑）。缺少作用域时会返回 403。

7. 访问令牌声明

解码后的 JWT 声明会由依赖项直接返回：

@app.get("/api/profile")
async def profile(claims: dict = Depends(auth0.require_auth())):
    return {
        "sub": claims["sub"],       # user ID
        "scope": claims.get("scope"),  # granted scopes
    }

关键声明：

• claims["sub"] — 用户/客户端 ID
• claims["scope"] — 以空格分隔的已授权作用域
• claims["iss"] — 签发者（你的 Auth0 域名 URL）
• claims["aud"] — 受众
• claims["exp"] — 过期时间戳
• claims["iat"] — 签发时间戳

8. 无需访问声明即可保护路由

@app.get("/api/protected", dependencies=[Depends(auth0.require_auth())])
async def protected():
    return {"message": "You need a valid access token to see this."}

9. 测试 API

# No token — expect 401
curl http://localhost:8000/api/private

# With a valid access token
curl http://localhost:8000/api/private \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

通过 Client Credentials 流程或 Auth0 Dashboard → APIs → Test 标签页获取测试令牌。

---

常见错误

错误	修复方法
在源代码中硬编码 domain 或 audience	始终从环境变量读取，切勿将凭据写入代码
直接使用 python-jose 或 PyJWT	不需要；auth0-fastapi-api 会通过 JWKS 处理所有验证
手动解析 Authorization 标头	SDK 会自动提取并验证令牌
手动调用 jwt.decode()	SDK 会根据 JWKS 端点验证令牌，请勿自行验证
使用 fastapi-users 验证 Auth0 JWT	该软件包用于用户管理，而非验证 Auth0 JWT
在 Auth0 中创建了 Application，而不是 API	必须创建 API 资源（Applications → APIs）；Application 不会签发具有正确受众的访问令牌
将包含 https:// 的完整 URL 作为 domain 传入	domain 应为不带协议的域名，例如 my-tenant.us.auth0.com，而不是 https://my-tenant.us.auth0.com
使用 ID 令牌而不是访问令牌	API 身份验证必须使用访问令牌；ID 令牌用于客户端应用，而非 API 授权
未为 SPA 客户端配置 CORS	添加 CORSMiddleware，以允许来自前端源的请求
os.getenv() 会静默返回 None	确保已安装 python-dotenv，并在初始化 Auth0FastAPI() 前调用 load_dotenv()；或者使用 os.environ[]，以便快速报错

---

DPoP 支持

内置符合 RFC 9449 的持有证明令牌绑定。混合模式下默认启用 DPoP（同时接受 Bearer 和 DPoP 令牌）。配置详情请参阅集成指南。

---

相关技能

• auth0-quickstart - Auth0 基础设置和框架检测
• auth0-mfa - 添加多因素身份验证
• auth0-cli - 在终端中管理 Auth0 资源

---

快速参考

Auth0FastAPI 配置：

auth0 = Auth0FastAPI(
    domain=os.getenv("AUTH0_DOMAIN"),       # required (or use domains)
    audience=os.getenv("AUTH0_AUDIENCE"),    # required
    dpop_enabled=True,                       # default; set False for Bearer-only
    dpop_required=False,                     # default; set True to reject Bearer tokens
)

路由保护：

Depends(auth0.require_auth())                    # any valid token
Depends(auth0.require_auth(scopes="read:res"))   # single scope
Depends(auth0.require_auth(scopes=["r", "w"]))   # all scopes required

访问声明：

claims["sub"]           # user/client ID
claims["scope"]         # space-separated scopes

环境变量：

• AUTH0_DOMAIN — 你的 Auth0 租户域名（例如 tenant.us.auth0.com）
• AUTH0_AUDIENCE — 你的 API 标识符（例如 https://api.example.com）

常见用例：

• 保护路由 → Depends(auth0.require_auth())（参见步骤 5）
• 作用域强制执行 → Depends(auth0.require_auth(scopes="..."))（参见步骤 6）
• DPoP 令牌绑定 → 集成指南
• 反向代理设置 → 集成指南
• 高级配置 → API 参考

---

详细文档

• 设置指南 — Auth0 CLI 设置、环境配置、获取测试令牌
• 集成指南 — DPoP、作用域、错误处理、反向代理、测试
• API 参考 — 完整的构造函数选项、方法签名、错误代码

---

参考资料

• auth0-fastapi-api GitHub
• PyPI 上的 auth0-fastapi-api
• Auth0 FastAPI API 快速入门
• FastAPI 依赖注入
• 访问令牌指南