Skip to content

Commit 1ee3e4c

Browse files
yogeshchoudhary147yogeshchoudhary147
authored
feat: add dedicated auth0-dpop skill (#136)
* feat: add auth0-dpop skill, reference from auth0-vue * fix: address coderabbit review comments * fix: move error handling to integration.md, fix Angular fetcher lifecycle
1 parent aacefa7 commit 1ee3e4c

6 files changed

Lines changed: 610 additions & 0 deletions

File tree

‎plugins/auth0/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ npx skills add auth0/agent-skills/plugins/auth0
3131
| [auth0-quickstart](skills/auth0-quickstart) | Detects the project's framework and guides through a complete Auth0 integration from scratch. Handles tenant and application setup, environment variable configuration, and routes to the correct SDK skill. | [SKILL.md](skills/auth0-quickstart/SKILL.md) |
3232
| [auth0-migration](skills/auth0-migration) | Guides migration of existing authentication to Auth0 from other providers (Firebase, Cognito, Supabase, Clerk, custom). Covers user import strategies, JWT validation updates, and gradual migration patterns. | [SKILL.md](skills/auth0-migration/SKILL.md) |
3333
| [auth0-mfa](skills/auth0-mfa) | Implements Multi-Factor Authentication. Covers factor setup (TOTP, SMS, email, push, WebAuthn, voice), step-up authentication for sensitive operations, and adaptive MFA policies. | [SKILL.md](skills/auth0-mfa/SKILL.md) |
34+
| [auth0-dpop](skills/auth0-dpop) | Adds DPoP (Demonstrating Proof-of-Possession) token binding to SPAs. Covers API setup, enabling `useDpop`, DPoP-aware API calls with `createFetcher`, multiple API targets, nonce handling, and error handling across Vue, React, Angular, and auth0-spa-js. | [SKILL.md](skills/auth0-dpop/SKILL.md) |
3435
| [acul-screen-generator](skills/acul-screen-generator) | Generates complete, branded ACUL screen implementations using the React or Vanilla JS SDK. Handles project setup, screen generation, theming, and dev mode wiring. | [SKILL.md](skills/acul-screen-generator/SKILL.md) |
3536
| [auth0-spa-js](skills/auth0-spa-js) | Integrates `@auth0/auth0-spa-js` into Vanilla JS, Svelte, SolidJS, and any framework-agnostic SPA. Covers client initialization, login/logout, token retrieval, refresh token rotation, and calling protected APIs without a framework-specific wrapper. | [SKILL.md](skills/auth0-spa-js/SKILL.md) |
3637
| [auth0-react](skills/auth0-react) | Integrates `@auth0/auth0-react` into React SPAs (Vite or Create React App). Covers provider setup, login/logout, protected routes, and API calls with access tokens using React hooks. | [SKILL.md](skills/auth0-react/SKILL.md) |

‎plugins/auth0/skills/auth0-dpop/SKILL.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
name: auth0-dpop
3+
description: Use when adding DPoP (Demonstrating Proof-of-Possession) token binding to protect API calls with device-bound, sender-constrained access tokens that cannot be replayed if stolen. Also use when a user says "bind tokens to the client", "prevent token theft", or "sender-constrained tokens".
4+
license: Apache-2.0
5+
metadata:
6+
author: Auth0 <support@auth0.com>
7+
version: '1.0.0'
8+
openclaw:
9+
emoji: "\U0001F511"
10+
homepage: https://github.com/auth0/agent-skills
11+
requires:
12+
bins:
13+
- auth0
14+
os:
15+
- darwin
16+
- linux
17+
install:
18+
- id: brew
19+
kind: brew
20+
package: auth0/auth0-cli/auth0
21+
bins: [auth0]
22+
label: 'Install Auth0 CLI (brew)'
23+
---
24+
25+
# Auth0 DPoP Guide
26+
27+
Bind access tokens to the client's cryptographic key so stolen tokens cannot be replayed.
28+
29+
---
30+
31+
## Overview
32+
33+
### What is DPoP?
34+
35+
DPoP (Demonstrating Proof-of-Possession) is an OAuth 2.0 mechanism defined in
36+
[RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449) that cryptographically
37+
binds access tokens to a client-held key pair. Each API request includes a
38+
short-lived signed JWT (the DPoP proof) that proves the sender holds the private
39+
key — a stolen token alone cannot be replayed by an attacker.
40+
41+
### When to Use This Skill
42+
43+
- Protecting high-value API calls against token theft and replay attacks
44+
- Meeting security or compliance requirements that mandate sender-constrained tokens
45+
- Any SPA or Vanilla JS app calling a protected Auth0 API with elevated security needs
46+
47+
### When NOT to Use This Skill
48+
49+
- **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.)
50+
- **APIs that don't support DPoP** — the resource server must be configured to accept DPoP token dialect; Bearer-only APIs will reject DPoP proofs
51+
- **Flows requiring token sharing** — DPoP tokens are bound to a single key pair and cannot be forwarded to or reused by another client
52+
53+
### Requirements
54+
55+
- Auth0 tenant with DPoP-capable authorization server
56+
- API resource server with DPoP token dialect enabled
57+
- A browser SPA using one of: `@auth0/auth0-vue`, `@auth0/auth0-react`,
58+
`@auth0/auth0-angular`, or `@auth0/auth0-spa-js`
59+
- HTTPS in production (required by Auth0 for DPoP)
60+
61+
### Key Concepts
62+
63+
| Concept | Description |
64+
|---------|-------------|
65+
| DPoP Proof | A short-lived signed JWT attached to each request proving key possession |
66+
| DPoP Nonce | A server-issued value that must be included in the proof to prevent replay |
67+
| `useDpop: true` | SDK option that enables automatic DPoP proof generation |
68+
| `createFetcher()` | SDK helper that returns a `fetch`-compatible function handling proofs automatically |
69+
| `UseDpopNonceError` | Error thrown when the server rotates its nonce mid-flight; retry with the new nonce |
70+
71+
---
72+
73+
## Step 1: Enable DPoP on Your API
74+
75+
### Via Auth0 Dashboard
76+
77+
1. Go to **Applications → APIs**
78+
2. Select the API your SPA calls
79+
3. Under the **Settings** tab, confirm the API identifier matches your `audience`
80+
4. No additional toggle is needed in the dashboard — DPoP is enabled per-request
81+
by the client when the API resource server is configured to accept DPoP tokens
82+
83+
### Via Auth0 CLI
84+
85+
```bash
86+
# Inspect current resource server settings
87+
auth0 api get "resource-servers" | jq '.[] | select(.identifier == "https://your-api-identifier")'
88+
89+
# Enable DPoP token dialect on the API
90+
auth0 api patch "resource-servers/{API_ID}" \
91+
--data '{"token_dialect": "access_token_authz"}'
92+
```
93+
94+
> Replace `{API_ID}` with the ID returned from the GET call above.
95+
96+
---
97+
98+
## Step 2: Configure Your Application
99+
100+
### Common pattern across all frameworks
101+
102+
1. Add `useDpop: true` to your Auth0 client/provider configuration alongside your `audience`
103+
2. Use `createFetcher()` instead of attaching tokens manually — the SDK handles
104+
proof generation, nonce management, and header injection for you
105+
3. Handle `UseDpopNonceError` in cases where the server rotates its nonce
106+
107+
### Environment variables
108+
109+
Ensure your `.env` includes the API audience:
110+
111+
```bash
112+
# Vite
113+
VITE_AUTH0_DOMAIN=your-tenant.auth0.com
114+
VITE_AUTH0_CLIENT_ID=your-client-id
115+
VITE_AUTH0_AUDIENCE=https://your-api-identifier
116+
```
117+
118+
---
119+
120+
## Additional Resources
121+
122+
### [Framework Examples](references/examples.md)
123+
Complete implementation examples for all supported frameworks:
124+
- Vue.js
125+
- React
126+
- Angular
127+
- auth0-spa-js (Vanilla JS)
128+
129+
### [Integration Guide](references/integration.md)
130+
Error handling and troubleshooting:
131+
- `UseDpopNonceError` — nonce rotation handling
132+
- Common issues
133+
134+
---
135+
136+
## Related Skills
137+
138+
- `auth0-vue` - Vue.js Auth0 integration
139+
- `auth0-react` - React Auth0 integration
140+
- `auth0-angular` - Angular Auth0 integration
141+
- `auth0-spa-js` - Vanilla JS / framework-agnostic SPA integration
142+
- `auth0-mfa` - Multi-factor authentication
143+
144+
---
145+
146+
## References
147+
148+
- [Auth0 DPoP Documentation](https://auth0.com/docs/secure/tokens/access-tokens/dpop)
149+
- [RFC 9449 — OAuth 2.0 Demonstrating Proof of Possession](https://datatracker.ietf.org/doc/html/rfc9449)
150+
- [auth0-spa-js Releases](https://github.com/auth0/auth0-spa-js/releases)

0 commit comments

Comments
 (0)