Guide · Agent skill
How to use the DPoP OAuth Adoption agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The dpop-adoption skill is an agent skill from google/skills (Identity category, Apache-2.0) that gives an AI agent detailed rules for adding DPoP (RFC 9449) to an app that uses Google OAuth refresh tokens. DPoP ties a refresh token to a private key held by the client, so a stolen token is harder to reuse. This guide is for developers with an existing OAuth integration, and it explains how to install the skill, ask for the right help and check the output.
DPoP OAuth Adoptiongoogle/skills · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the dpop-adoption skill ZIP from this page.
- 2Unzip into a skills folder. Place the dpop-adoption folder in ~/.claude/skills/ for personal use, or in your project's .claude/skills/ folder.
- 3Or upload it in the Claude apps. Go to Settings → Capabilities → Skills and upload the ZIP.
- 4Confirm your prerequisites. Check that you have Node.js 18+ or a modern browser with WebCrypto, and a registered Google OAuth client.
- 5Ask for the DPoP task. Describe what you need, such as adding DPoP to the refresh token flow or fixing use_dpop_nonce.
- 6Review the generated code. Check that the private key is non-extractable, the proof header is correct and the htu is stripped of query and hash.
- 7Test the token endpoint. Run your refresh flow and confirm it handles the use_dpop_nonce challenge.
What is an agent skill and what does this one make the agent do?
An agent skill is a folder with a SKILL.md file that gives an AI agent specialised instructions it can load when a task matches. The skill's description tells the agent when to use it, so you usually don't need to name it in your request.
This skill gives the agent rules for DPoP at Google's token endpoint. It covers generating non-extractable P-256 key pairs, building correctly formatted DPoP proof JWTs, binding the proof to the authorization code, encoding ECDSA signatures in the raw 64-byte format, and handling the use_dpop_nonce retry at oauth2.googleapis.com/token. It also explains that pure single-page apps generally need a backend-for-frontend (BFF) server to use DPoP with Google APIs.
How do you install the dpop-adoption skill?
Download the ZIP of the skill from this page. The skill ships as a single file, SKILL.md, inside the skills/identity/dpop-adoption folder.
For a personal setup, unzip the download into ~/.claude/skills/ so the dpop-adoption folder sits there. To scope it to one project, unzip it into that project's .claude/skills/ folder instead.
To use it in the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/dpop-adoption/
- Project only: <your-project>/.claude/skills/dpop-adoption/
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
What do you need before you start?
The skill assumes you already have an OAuth integration with Google. Its listed requirements are Node.js 18+ or a modern browser with WebCrypto support, and a Google OAuth client registered for the Google OAuth 2.0 platform.
The skill runs no scripts and makes no network calls itself. It only guides the code your agent writes in your project.
- Node.js 18 or newer, or a modern browser with WebCrypto
- A Google OAuth client registered for the Google OAuth 2.0 platform
- An existing OAuth flow that uses refresh tokens
How do you trigger the skill with natural requests?
Describe the task in plain terms that match the skill's scope: adding DPoP, generating the key pair, building proof JWTs, or fixing a use_dpop_nonce error at the token endpoint. Name Google and the token endpoint if you can, since the skill is written for that platform.
Example requests you can type:
- Add DPoP sender-constraining to our Google OAuth refresh token flow in this Node app.
- Generate a non-extractable P-256 key pair for DPoP and export the public JWK.
- Our token refresh to oauth2.googleapis.com/token returns 400 use_dpop_nonce. Fix the retry loop.
- Build a createDPoPProof helper that binds the proof to the authorization code.
- Does our single-page app need a backend-for-frontend to use DPoP with Google APIs?
What does the generated code look like?
The skill specifies the DPoP proof header and the helper function names your agent should create. The header uses typ dpop+jwt, alg ES256, and the public key as a jwk. The htu claim is stripped of query and hash, with sanitizeHTU defined as shown below.
Keep the private key non-extractable. The public key must stay exportable so it can be emitted as a JWK. Public JWKs should contain only kty, crv, x and y.
- Private key: extractable false
- Public key: extractable true
- Public JWK fields: kty EC, crv P-256, x, y (no padding)
// Header
{
"typ": "dpop+jwt",
"alg": "ES256",
"jwk": await exportPublicJWK(publicKey)
}
export function sanitizeHTU(htu) {
const u = new URL(htu);
return `${u.origin}${u.pathname}`;
}How do you check the output and debug proof errors?
Ask the agent to verify the proof with the verifyDPoPProof export, which returns isValid, header, payload and error. The skill notes that a raw 64-byte WebCrypto ECDSA signature must be base64url-encoded directly; converting it from DER will throw an Invalid DER sequence error.
If Google returns 400 use_dpop_nonce, the skill tells the agent to retry the token request with the nonce supplied in the DPoP-Nonce response header. Ask the agent to show the retry loop so you can confirm it stops after a successful response.
- Signature errors: check you are not converting WebCrypto output from DER
- Nonce loops: confirm the nonce from the response is included in the next proof
- SPA failures: consider a BFF server, as the skill recommends
What people use it for
- Adding DPoP to a Node.js backend that refreshes Google OAuth tokens.
- Generating non-extractable P-256 key pairs in a browser app using WebCrypto.
- Debugging an invalid DPoP proof signature in an existing token helper.
- Fixing a use_dpop_nonce retry loop at oauth2.googleapis.com/token.
- Deciding whether a browser SPA should move token handling into a BFF server.
Frequently asked questions
Is the dpop-adoption skill free to use?
The skill is published under the Apache-2.0 licence, as listed on this page. This page does not list a price, so check the licence text in the source repository for terms.
What do I need to install the dpop-adoption skill?
You need the SKILL.md file from the ZIP on this page and a Claude setup that loads skills. Unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload the ZIP under Settings → Capabilities → Skills.
Does the dpop-adoption skill run scripts or access the network?
No. This page lists that the skill runs no scripts and uses no network. It gives the agent guidance for the code it writes in your project.
Does DPoP work in a single-page app without a backend?
The skill says pure client-side SPAs generally cannot use DPoP directly with Google APIs, because of client_secret requirements and CORS limits on the DPoP-Nonce header. It recommends a backend-for-frontend server that handles authorization and token refresh.
What does the skill not cover?
It does not apply to unconstrained OAuth 2.0 flows where refresh tokens are not bound to a client key pair. It also excludes Google Cloud IAM and service account authentication.
How is this different from a general OAuth guide?
It is narrow. It focuses on DPoP at Google's token endpoint, including key generation, proof JWT claims and the nonce retry. It is not a general introduction to OAuth.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you already run a Google OAuth integration with refresh tokens and need DPoP proofs, key handling or nonce retries done correctly. Skip it if you are new to OAuth, do not use refresh tokens bound to a client key pair, or need Google Cloud IAM or service account help.
Download the skill