mcpField
A
auth0-dpop

auth0-dpop

github.com/auth0安全5567 次安装1 天前更新
代码仓库

关于 auth0-dpop

介绍如何使用 Auth0 DPoP 将访问令牌绑定到客户端持有的密钥对，涵盖 SPA 配置、证明与随机数处理，以及受支持的 Auth0 SDK。

主要功能

  1. 01说明 DPoP 令牌绑定
  2. 02配置 Auth0 API 的 DPoP
  3. 03通过 SDK 启用证明生成
  4. 04处理随机数轮换错误
  5. 05提供受支持 SPA 框架示例

适用场景

  1. 01防止 API 调用中的令牌重放
  2. 02为 SPA 添加发送方约束令牌
  3. 03处理服务器签发的 DPoP 随机数
  4. 04配置支持 DPoP 的 API

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/auth0/agent-skills --skill auth0-dpop

安装后在 Claude Code 中输入/auth0-dpop确认已加载。

附带文件references/examples.mdreferences/integration.md

详细介绍

Auth0 DPoP 指南

将访问令牌绑定到客户端的加密密钥，防止被盗令牌遭到重放。

概述

什么是 DPoP？

DPoP（持有证明）是一种由 RFC 9449 定义的 OAuth 2.0 机制，可通过加密方式 将访问令牌绑定到客户端持有的密钥对。每个 API 请求都包含一个 短时有效的签名 JWT（DPoP 证明），用于证明发送方持有私钥——攻击者仅凭被盗令牌 无法进行重放。

何时使用此技能
  • 保护高价值 API 调用，抵御令牌盗窃和重放攻击
  • 满足要求使用发送方受限令牌的安全或合规要求
  • 任何以较高安全要求调用受保护 Auth0 API 的 SPA 或 Vanilla JS 应用
何时不应使用此技能
  • SSR / 服务端环境——DPoP 依赖存储在浏览器中的私钥；无法在服务端安全使用（Next.js、Nuxt 等）
  • 不支持 DPoP 的 API——资源服务器必须配置为接受 DPoP 令牌类型；仅支持 Bearer 的 API 会拒绝 DPoP 证明
  • 需要共享令牌的流程——DPoP 令牌绑定到单个密钥对，无法转发给其他客户端或由其他客户端重复使用
要求
  • 配置了支持 DPoP 的授权服务器的 Auth0 租户
  • 启用了 DPoP 令牌类型的 API 资源服务器
  • 使用以下 SDK 之一的浏览器 SPA：@auth0/auth0-vue、@auth0/auth0-react、 @auth0/auth0-angular 或 @auth0/auth0-spa-js
  • 生产环境使用 HTTPS（Auth0 对 DPoP 的要求）
关键概念
概念描述
DPoP 证明随每个请求附带的短时有效签名 JWT，用于证明持有密钥
DPoP 随机数服务器签发的值，必须包含在证明中以防止重放
useDpop: true用于启用自动生成 DPoP 证明的 SDK 选项
createFetcher()SDK 辅助函数，返回兼容 fetch 的函数并自动处理证明
UseDpopNonceError服务器在请求过程中轮换随机数时抛出的错误；使用新的随机数重试

步骤 1：在 API 上启用 DPoP

通过 Auth0 控制台
  1. 前往 Applications → APIs
  2. 选择 SPA 调用的 API
  3. 在 Settings 选项卡下，确认 API 标识符与 audience 一致
  4. 控制台中无需额外切换设置——当 API 资源服务器配置为接受 DPoP 令牌时， 客户端会为每个请求启用 DPoP
通过 Auth0 CLI
# Inspect current resource server settings
auth0 api get "resource-servers" | jq '.[] | select(.identifier == "https://your-api-identifier")'

# Enable DPoP token dialect on the API
auth0 api patch "resource-servers/{API_ID}" \
  --data '{"token_dialect": "access_token_authz"}'

将 {API_ID} 替换为上述 GET 调用返回的 ID。

步骤 2：配置应用

所有框架通用的模式
  1. 在 Auth0 客户端/提供程序配置中，将 useDpop: true 与 audience 一同添加
  2. 使用 createFetcher()，而不是手动附加令牌——SDK 会为你处理 证明生成、随机数管理和请求头注入
  3. 在服务器轮换随机数时处理 UseDpopNonceError
环境变量

确保 .env 中包含 API audience：

# Vite
VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=your-client-id
VITE_AUTH0_AUDIENCE=https://your-api-identifier

更多资源

框架示例

所有受支持框架的完整实现示例：

  • Vue.js
  • React
  • Angular
  • auth0-spa-js（Vanilla JS）
集成指南

错误处理与故障排查：

  • UseDpopNonceError——随机数轮换处理
  • 常见问题

相关技能

  • auth0-vue - Vue.js Auth0 集成
  • auth0-react - React Auth0 集成
  • auth0-angular - Angular Auth0 集成
  • auth0-spa-js - Vanilla JS / 框架无关的 SPA 集成
  • auth0-mfa - 多因素身份验证

参考资料

评论

支持 Markdown