Back to Details

auth0-dpop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Auth0 DPoP Guide

Auth0 DPoP 指南

Bind access tokens to the client's cryptographic key so stolen tokens cannot be replayed.
将访问令牌绑定到客户端的加密密钥，使被盗令牌无法被重放。

Overview

概述

What is DPoP?

什么是DPoP？

DPoP (Demonstrating Proof-of-Possession) is an OAuth 2.0 mechanism defined in RFC 9449 that cryptographically binds access tokens to a client-held key pair. Each API request includes a short-lived signed JWT (the DPoP proof) that proves the sender holds the private key — a stolen token alone cannot be replayed by an attacker.
DPoP（Demonstrating Proof-of-Possession，持有证明）是OAuth 2.0的一种机制，定义在 RFC 9449中，它通过加密方式将访问令牌与客户端持有的密钥对绑定。每个API请求都包含一个短期签名的JWT（即DPoP证明），用于证明发送方持有私钥——仅被盗取的令牌无法被攻击者重放。

When to Use This Skill

何时使用此技能

  • Protecting high-value API calls against token theft and replay attacks
  • Meeting security or compliance requirements that mandate sender-constrained tokens
  • Any SPA or Vanilla JS app calling a protected Auth0 API with elevated security needs
  • 保护高价值API调用免受令牌被盗和重放攻击
  • 满足要求使用受发送方限制令牌的安全或合规需求
  • 任何调用受保护Auth0 API且有较高安全需求的SPA或Vanilla JS应用

When NOT to Use This Skill

何时不使用此技能

  • SSR / server-side environments — DPoP relies on a private key held in the browser; it cannot be safely used server-side (Next.js, Nuxt, etc.)
  • APIs that don't support DPoP — the resource server must be configured to accept DPoP token dialect; Bearer-only APIs will reject DPoP proofs
  • Flows requiring token sharing — DPoP tokens are bound to a single key pair and cannot be forwarded to or reused by another client
  • SSR / 服务器端环境 —— DPoP依赖于浏览器中存储的私钥，无法在服务器端安全使用（如Next.js、Nuxt等）
  • 不支持DPoP的API —— 资源服务器必须配置为接受DPoP令牌格式；仅支持Bearer令牌的API会拒绝DPoP证明
  • 需要共享令牌的流程 —— DPoP令牌绑定到单个密钥对，无法转发给其他客户端或被其复用

Requirements

要求

  • Auth0 tenant with DPoP-capable authorization server
  • API resource server with DPoP token dialect enabled
  • A browser SPA using one of: 
    @auth0/auth0-vue
    , 
    @auth0/auth0-react
    , 
    @auth0/auth0-angular
    , or 
    @auth0/auth0-spa-js
  • HTTPS in production (required by Auth0 for DPoP)
  • 具备DPoP能力的Auth0租户授权服务器
  • 已启用DPoP令牌格式的API资源服务器
  • 使用以下任一库的浏览器SPA：
    @auth0/auth0-vue
    、
    @auth0/auth0-react
    、 
    @auth0/auth0-angular
    或
    @auth0/auth0-spa-js
  • 生产环境中使用HTTPS（Auth0对DPoP有此要求）

Key Concepts

核心概念

ConceptDescription
DPoP ProofA short-lived signed JWT attached to each request proving key possession
DPoP NonceA server-issued value that must be included in the proof to prevent replay
useDpop: true
SDK option that enables automatic DPoP proof generation
createFetcher()
SDK helper that returns a 
fetch
-compatible function handling proofs automatically
UseDpopNonceError
Error thrown when the server rotates its nonce mid-flight; retry with the new nonce
概念描述
DPoP Proof附加在每个请求上的短期签名JWT，用于证明密钥持有
DPoP Nonce服务器颁发的值，必须包含在证明中以防止重放
useDpop: true
启用自动生成DPoP证明的SDK选项
createFetcher()
SDK辅助函数，返回一个兼容
fetch
的函数，可自动处理证明
UseDpopNonceError
当服务器中途轮换nonce时抛出的错误；需使用新nonce重试

Step 1: Enable DPoP on Your API

步骤1：在你的API上启用DPoP

Via Auth0 Dashboard

通过Auth0控制台

  1. Go to Applications → APIs
  2. Select the API your SPA calls
  3. Under the Settings tab, confirm the API identifier matches your 
    audience
  4. No additional toggle is needed in the dashboard — DPoP is enabled per-request by the client when the API resource server is configured to accept DPoP tokens
  1. 前往Applications → APIs
  2. 选择你的SPA调用的API
  3. 在Settings标签页下，确认API标识符与你的
    audience
    匹配
  4. 控制台中无需额外开关——当API资源服务器配置为接受DPoP令牌时，客户端可在请求中启用DPoP

Via Auth0 CLI

通过Auth0 CLI

bash
undefined
bash
undefined

Inspect current resource server settings

检查当前资源服务器设置

auth0 api get "resource-servers" | jq '.[] | select(.identifier == "https://your-api-identifier")'
auth0 api get "resource-servers" | jq '.[] | select(.identifier == "https://your-api-identifier")'

Enable DPoP token dialect on the API

在API上启用DPoP令牌格式

auth0 api patch "resource-servers/{API_ID}"
--data '{"token_dialect": "access_token_authz"}'

> Replace `{API_ID}` with the ID returned from the GET call above.

---
auth0 api patch "resource-servers/{API_ID}"
--data '{"token_dialect": "access_token_authz"}'

> 替换`{API_ID}`为上述GET请求返回的ID。

---

Step 2: Configure Your Application

步骤2：配置你的应用

Common pattern across all frameworks

所有框架通用模式

  1. Add 
    useDpop: true
    to your Auth0 client/provider configuration alongside your 
    audience
  2. Use 
    createFetcher()
    instead of attaching tokens manually — the SDK handles proof generation, nonce management, and header injection for you
  3. Handle 
    UseDpopNonceError
    in cases where the server rotates its nonce
  1. 在Auth0客户端/提供者配置中添加
    useDpop: true
    ，与
    audience
    一同配置
  2. 使用
    createFetcher()
    替代手动附加令牌——SDK会自动处理证明生成、nonce管理和头部注入
  3. 在服务器轮换nonce的情况下处理
    UseDpopNonceError

Environment variables

环境变量

Ensure your 
.env
includes the API audience:
bash
undefined
确保你的
.env
文件包含API audience：
bash
undefined

Vite

Vite

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

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

---

Additional Resources

额外资源

Framework Examples

框架示例

Complete implementation examples for all supported frameworks:
  • Vue.js
  • React
  • Angular
  • auth0-spa-js (Vanilla JS)
所有支持框架的完整实现示例：
  • Vue.js
  • React
  • Angular
  • auth0-spa-js（Vanilla JS）

Integration Guide

集成指南

Error handling and troubleshooting:
  • UseDpopNonceError
    — nonce rotation handling
  • Common issues
错误处理与故障排除：
  • UseDpopNonceError
    ——nonce轮换处理
  • 常见问题

Related Skills

相关技能

  • auth0-vue
    - Vue.js Auth0 integration
  • auth0-react
    - React Auth0 integration
  • auth0-angular
    - Angular Auth0 integration
  • auth0-spa-js
    - Vanilla JS / framework-agnostic SPA integration
  • auth0-mfa
    - Multi-factor authentication
  • auth0-vue
    - Vue.js Auth0集成
  • auth0-react
    - React Auth0集成
  • auth0-angular
    - Angular Auth0集成
  • auth0-spa-js
    - Vanilla JS/无框架依赖SPA集成
  • auth0-mfa
    - 多因素认证

References

参考资料