DPoP Adoption & Identity Security Architecture
Demonstrating Proof-of-Possession (DPoP, RFC 9449) secures OAuth 2.0 refresh
tokens against interception and replay attacks by cryptographically binding them
to a private key held exclusively by the client. In Google's OAuth 2.0 platform,
DPoP binds the refresh token at the token endpoint, while access tokens issued
for Google APIs are standard Bearer tokens (token_type: "Bearer").
1. Core Cryptographic & Architectural Invariants
When implementing DPoP helpers or upgrading HTTP clients, you MUST adhere to the
following strict security invariants:
A. Universal WebCrypto & Runtime Compatibility
- In modern ES6 JavaScript (
"type": "module" for Node 18+ and browsers),
ALWAYS access globalThis.crypto directly after verifying the environment
context.
- NEVER import legacy CommonJS modules via
require('node:crypto') or
reference browser-scoped window.crypto, as these cause module
initialization crashes across hybrid runtimes.
B. Hardware-Backed Non-Extractable Key Persistence
- Generate an Elliptic Curve key pair on the SECP256R1 (
P-256) curve: { name: 'ECDSA', namedCurve: 'P-256' }.
- CRITICAL SECURITY GUARDRAIL: The private key MUST be configured as
non-extractable (
extractable: false). This guarantees the private key
can never leave the platform's cryptographic boundary (Secure Enclave,
Android KeyStore, or JS sandbox memory), thwarting XSS and dependency token
theft attacks.
- Runtime Persistence Scope: In-memory WebCrypto (
extractable: false)
key generation applies to browser/IndexedDB contexts and single-process
runtime harnesses; multi-instance or persistent server-side Node.js
deployments should bind DPoP private keys via KMS/HSM/TPM so bound refresh
tokens survive process restarts.
- The public key MUST remain exportable (
extractable: true) to allow
emitting JSON Web Keys (JWKs).
C. Public JWK Formatting Standards
- When exporting public keys to attach to DPoP Proof JWT headers, construct a
clean JWK dictionary containing strictly:
"kty": "EC"
"crv": "P-256"
"x": Base64URL-encoded x-coordinate without trailing equal sign
padding (=).
"y": Base64URL-encoded y-coordinate without trailing equal sign
padding (=).
- NEVER expose private key parameters (
"d") or superfluous metadata.
D. IEEE P1363 vs. ASN.1 DER Signature Disambiguation
- DPoP Proof JWTs require raw concatenated coordinate signatures ($R \parallel
S$, exactly 64 bytes for P-256) per IEEE P1363 and RFC 7518.
- WebCrypto Native Rule: In standard WebCrypto (
crypto.subtle.sign),
ECDSA signatures are ALREADY emitted natively in raw IEEE P1363 format
(concatenated 32-byte r and s buffers, 64 bytes total). DO NOT
attempt DER-to-Raw conversion on crypto.subtle.sign outputs, as parsing a
64-byte raw buffer as ASN.1 DER causes an immediate runtime exception
(Invalid DER sequence). Directly base64url-encode the raw ArrayBuffer.
- Legacy API Fallback: If and only if implementing in legacy Java/Android
(
java.security.Signature) or Node CommonJS (crypto.createSign), convert
ASN.1 DER output to raw 64-byte IEEE P1363 format before base64url encoding.
E. SPA & Backend-for-Frontend (BFF) Architecture
- Secretless SPAs Limitation: Pure client-side single-page applications
(SPAs) without a backend cannot use DPoP directly with Google APIs due to
client_secret requirements on server endpoints and browser CORS
limitations on the DPoP-Nonce response header.
- BFF Pattern: To secure SPAs with DPoP, route authorization and token
refresh requests through a Backend-for-Frontend (BFF) server-side client.
The BFF sets
access_type=offline, binds refresh tokens server-side using
DPoP, and maintains secure session cookies with the frontend.
2. Implementation Rules & Mandatory Public API
When creating new modules, your module MUST explicitly export all functions
below to integrate cleanly with CI/CD verification harnesses and automated
probers. When inspecting or refactoring existing codebases, ensure equivalent
cryptographic and RFC 9449 logic is present. Obey strict claim derivation logic
in all cases:
A. DPoP Proof JWT Claim Derivation Rules (createDPoPProof)
When generating the DPoP Proof JWT in createDPoPProof:
1. JOSE Header (typ, alg, jwk):
// Header
{
"typ": "dpop+jwt",
"alg": "ES256",
"jwk": await exportPublicJWK(publicKey)
}
2. Payload Claims:
"htm": Uppercase HTTP Method ("POST" for token requests).
"htu": Target URI stripped of query parameters and hash fragments using
sanitizeHTU(htu). For token requests, this is
https://oauth2.googleapis.com/token.
"iat": Current integer epoch timestamp in seconds
(Math.floor(Date.now() / 1000)).
"jti" (Critical Invariant):
- If an explicit
jti argument is provided to createDPoPProof, use that
exact string over all others.
- Otherwise, if an
authCode argument is provided (during initial code
exchange), set jti = await calculateAuthCodeJti(authCode) where
calculateAuthCodeJti computes base64url(sha256(authCode)) to ensure
the DPoP proof is cryptographically bound to the authorization code.
- Only if neither
jti nor authCode is provided, generate a fresh
cryptographic random string via generateRandomString() (such as
crypto.getRandomValues(new Uint8Array(24)) base64url encoded).
"ath" (Optional): If an accessToken argument is provided for RFC 9449
resource requests, compute base64url(sha256(accessToken)) via
calculateATH(accessToken) and inject it (RFC 9449 Section 6.1).
"nonce" (Optional): If a nonce argument is provided, inject it directly
into the payload.
B. Explicit Export Signatures
// 1. Key generation & JWK export
export async function generateDPoPKeyPair() // -> { publicKey, privateKey } (private key extractable=false)
export async function exportPublicJWK(publicKey) // -> { kty: 'EC', crv: 'P-256', x, y }
// 2. Proof generation & validation
export async function createDPoPProof({ privateKey, publicKey, htm, htu, nonce, accessToken, authCode, jti }) // -> signed JWT string
export async function verifyDPoPProof(dpopProofJwt) // -> { isValid: boolean, header, payload, error }
export function sanitizeHTU(htu) // -> URL stripped of query and hash: const u = new URL(htu); return `${u.origin}${u.pathname}`;
// 3. Cryptographic & encoding utilities
export function base64UrlEncode(buffer) // -> Uint8Array/ArrayBuffer to base64url string without '=' padding
export function base64UrlDecode(str) // -> base64url string to Uint8Array/Buffer
export function stringToBase64Url(str) // -> UTF-8 string to base64url
export function base64UrlToString(str) // -> base64url to UTF-8 string
export function generateRandomString(byteLength = 32) // -> cryptographic random base64url string
export async function calculateATH(accessToken) // -> base64url(sha256(accessToken)) per RFC 9449 Sec 6.1
export async function calculateAuthCodeJti(code) // -> base64url(sha256(code))
export async function generatePKCE() // -> { codeVerifier (>=43 chars), codeChallenge, codeChallengeMethod: 'S256' }
3. Token Endpoint & Resource Request Workflow
When integrating with Google's OAuth 2.0 platform:
- Token Endpoint Requests (
oauth2.googleapis.com/token):
- Attach the DPoP Proof JWT in the
DPoP HTTP header:
`DPoP: ${proofJwt}` when making POST requests for code exchange
(grant_type=authorization_code) and token refresh
(grant_type=refresh_token).
- Resource API Requests:
- Google's token endpoint returns
"token_type": "Bearer". Downstream
requests to Google APIs (e.g. Calendar, Drive, Gmail) use standard
`Authorization: Bearer ${accessToken}` headers without DPoP
headers.
- Single-Retry Nonce Challenge Loop & Workflow Isolation:
- If Google's token endpoint returns HTTP
400 Bad Request with
error: "use_dpop_nonce" and a "DPoP-Nonce" response header:
- Workflow Isolation: Google's authorization server enforces
workflow isolation between authorization code exchange and token
refresh, returning an HTTP
400 use_dpop_nonce challenge to
establish a fresh nonce namespace. This is standard RFC-compliant
protocol behavior, not a server failure.
- Cache the fresh nonce in client state (
this.dpopNonce).
- Immediately synthesize a new DPoP Proof JWT incorporating the
updated
nonce claim and a fresh jti.
- Replay the failed token request exactly once. If the retried
request fails, terminate immediately with an error to prevent
infinite recursion.
4. Concise Agent Egress Protocol
When prompted to synthesize or output code deliverables under this skill,
prioritize returning clean, directly importable code blocks without redundant
conversational preambles or repetitive filler. For conceptual or architectural
inquiries, provide standard direct answers.
5. References & Supporting Documentation
Developer Documentation (Google for Developers)
Developer Knowledge MCP Server
- Agents equipped with Model Context Protocol (
MCP) can query real-time
Google Developer documentation using the
Google Developer Knowledge MCP Server
(npx -y @google/mcp-developer-knowledge-server) via
developer_knowledge:search_documents and
developer_knowledge:get_documents.
Standards & RFC Specifications
1---2name: dpop-adoption3metadata:4 source: https://skillmd.com/skills/google/dpop-adoption5 version: "1.0.1"6 category: Identity7description: >-8 Implement and debug OAuth 2.0 DPoP (RFC 9449) refresh token sender-constraining9 for WebCrypto, Node.js ES6, and browser runtimes integrating with Google's OAuth10 platform. Use when configuring non-extractable asymmetric key pairs (P-256),11 generating DPoP Proof JWTs for authorization code exchange and token refresh, or12 handling 400 use_dpop_nonce challenge retry loops at oauth2.googleapis.com/token.13 Don't use for unconstrained OAuth 2.0 flows (where refresh tokens are not bound14 to a client key pair), or for Google Cloud IAM / service account authentication.15---1617# DPoP Adoption & Identity Security Architecture1819Demonstrating Proof-of-Possession (DPoP, RFC 9449) secures OAuth 2.0 refresh20tokens against interception and replay attacks by cryptographically binding them21to a private key held exclusively by the client. In Google's OAuth 2.0 platform,22DPoP binds the refresh token at the token endpoint, while access tokens issued23for Google APIs are standard Bearer tokens (`token_type: "Bearer"`).2425## 1. Core Cryptographic & Architectural Invariants2627When implementing DPoP helpers or upgrading HTTP clients, you MUST adhere to the28following strict security invariants:2930### A. Universal WebCrypto & Runtime Compatibility3132- In modern ES6 JavaScript (`"type": "module"` for Node 18+ and browsers),33 ALWAYS access `globalThis.crypto` directly after verifying the environment34 context.35- **NEVER** import legacy CommonJS modules via `require('node:crypto')` or36 reference browser-scoped `window.crypto`, as these cause module37 initialization crashes across hybrid runtimes.3839### B. Hardware-Backed Non-Extractable Key Persistence4041- Generate an Elliptic Curve key pair on the SECP256R1 (`P-256`) curve: `{42 name: 'ECDSA', namedCurve: 'P-256' }`.43- **CRITICAL SECURITY GUARDRAIL:** The private key MUST be configured as44 **non-extractable** (`extractable: false`). This guarantees the private key45 can never leave the platform's cryptographic boundary (Secure Enclave,46 Android KeyStore, or JS sandbox memory), thwarting XSS and dependency token47 theft attacks.48- **Runtime Persistence Scope:** In-memory WebCrypto (`extractable: false`)49 key generation applies to browser/IndexedDB contexts and single-process50 runtime harnesses; multi-instance or persistent server-side Node.js51 deployments should bind DPoP private keys via KMS/HSM/TPM so bound refresh52 tokens survive process restarts.53- The public key MUST remain exportable (`extractable: true`) to allow54 emitting JSON Web Keys (JWKs).5556### C. Public JWK Formatting Standards5758- When exporting public keys to attach to DPoP Proof JWT headers, construct a59 clean JWK dictionary containing strictly:60 - `"kty": "EC"`61 - `"crv": "P-256"`62 - `"x"`: Base64URL-encoded x-coordinate without trailing equal sign63 padding (`=`).64 - `"y"`: Base64URL-encoded y-coordinate without trailing equal sign65 padding (`=`).66- **NEVER** expose private key parameters (`"d"`) or superfluous metadata.6768### D. IEEE P1363 vs. ASN.1 DER Signature Disambiguation6970- DPoP Proof JWTs require raw concatenated coordinate signatures ($R \parallel71 S$, exactly 64 bytes for P-256) per IEEE P1363 and RFC 7518.72- **WebCrypto Native Rule:** In standard WebCrypto (`crypto.subtle.sign`),73 ECDSA signatures are ALREADY emitted natively in raw IEEE P1363 format74 (concatenated 32-byte `r` and `s` buffers, 64 bytes total). **DO NOT**75 attempt DER-to-Raw conversion on `crypto.subtle.sign` outputs, as parsing a76 64-byte raw buffer as ASN.1 DER causes an immediate runtime exception77 (`Invalid DER sequence`). Directly base64url-encode the raw ArrayBuffer.78- **Legacy API Fallback:** If and only if implementing in legacy Java/Android79 (`java.security.Signature`) or Node CommonJS (`crypto.createSign`), convert80 ASN.1 DER output to raw 64-byte IEEE P1363 format before base64url encoding.8182### E. SPA & Backend-for-Frontend (BFF) Architecture8384- **Secretless SPAs Limitation:** Pure client-side single-page applications85 (SPAs) without a backend cannot use DPoP directly with Google APIs due to86 `client_secret` requirements on server endpoints and browser CORS87 limitations on the `DPoP-Nonce` response header.88- **BFF Pattern:** To secure SPAs with DPoP, route authorization and token89 refresh requests through a Backend-for-Frontend (BFF) server-side client.90 The BFF sets `access_type=offline`, binds refresh tokens server-side using91 DPoP, and maintains secure session cookies with the frontend.9293## 2. Implementation Rules & Mandatory Public API9495When creating new modules, your module MUST explicitly export all functions96below to integrate cleanly with CI/CD verification harnesses and automated97probers. When inspecting or refactoring existing codebases, ensure equivalent98cryptographic and RFC 9449 logic is present. Obey strict claim derivation logic99in all cases:100101### A. DPoP Proof JWT Claim Derivation Rules (`createDPoPProof`)102103When generating the DPoP Proof JWT in `createDPoPProof`:104105**1. JOSE Header (`typ`, `alg`, `jwk`):**106```javascript107// Header108{109 "typ": "dpop+jwt",110 "alg": "ES256",111 "jwk": await exportPublicJWK(publicKey)112}113```114115**2. Payload Claims:**116- `"htm"`: Uppercase HTTP Method (`"POST"` for token requests).117- `"htu"`: Target URI stripped of query parameters and hash fragments using118 `sanitizeHTU(htu)`. For token requests, this is119 `https://oauth2.googleapis.com/token`.120- `"iat"`: Current integer epoch timestamp in seconds121 (`Math.floor(Date.now() / 1000)`).122- `"jti"` (Critical Invariant):123 1. If an explicit `jti` argument is provided to `createDPoPProof`, use that124 exact string over all others.125 2. Otherwise, if an `authCode` argument is provided (during initial code126 exchange), set `jti = await calculateAuthCodeJti(authCode)` where127 `calculateAuthCodeJti` computes `base64url(sha256(authCode))` to ensure128 the DPoP proof is cryptographically bound to the authorization code.129 3. Only if neither `jti` nor `authCode` is provided, generate a fresh130 cryptographic random string via `generateRandomString()` (such as131 `crypto.getRandomValues(new Uint8Array(24))` base64url encoded).132- `"ath"` (Optional): If an `accessToken` argument is provided for RFC 9449133 resource requests, compute `base64url(sha256(accessToken))` via134 `calculateATH(accessToken)` and inject it (RFC 9449 Section 6.1).135- `"nonce"` (Optional): If a `nonce` argument is provided, inject it directly136 into the payload.137138### B. Explicit Export Signatures139140```javascript141// 1. Key generation & JWK export142export async function generateDPoPKeyPair() // -> { publicKey, privateKey } (private key extractable=false)143export async function exportPublicJWK(publicKey) // -> { kty: 'EC', crv: 'P-256', x, y }144145// 2. Proof generation & validation146export async function createDPoPProof({ privateKey, publicKey, htm, htu, nonce, accessToken, authCode, jti }) // -> signed JWT string147export async function verifyDPoPProof(dpopProofJwt) // -> { isValid: boolean, header, payload, error }148export function sanitizeHTU(htu) // -> URL stripped of query and hash: const u = new URL(htu); return `${u.origin}${u.pathname}`;149150// 3. Cryptographic & encoding utilities151export function base64UrlEncode(buffer) // -> Uint8Array/ArrayBuffer to base64url string without '=' padding152export function base64UrlDecode(str) // -> base64url string to Uint8Array/Buffer153export function stringToBase64Url(str) // -> UTF-8 string to base64url154export function base64UrlToString(str) // -> base64url to UTF-8 string155export function generateRandomString(byteLength = 32) // -> cryptographic random base64url string156export async function calculateATH(accessToken) // -> base64url(sha256(accessToken)) per RFC 9449 Sec 6.1157export async function calculateAuthCodeJti(code) // -> base64url(sha256(code))158export async function generatePKCE() // -> { codeVerifier (>=43 chars), codeChallenge, codeChallengeMethod: 'S256' }159```160161## 3. Token Endpoint & Resource Request Workflow162163When integrating with Google's OAuth 2.0 platform:1641651. **Token Endpoint Requests (`oauth2.googleapis.com/token`):**166 - Attach the DPoP Proof JWT in the `DPoP` HTTP header:167 `` `DPoP: ${proofJwt}` `` when making `POST` requests for code exchange168 (`grant_type=authorization_code`) and token refresh169 (`grant_type=refresh_token`).1702. **Resource API Requests:**171 - Google's token endpoint returns `"token_type": "Bearer"`. Downstream172 requests to Google APIs (e.g. Calendar, Drive, Gmail) use standard173 `` `Authorization: Bearer ${accessToken}` `` headers without DPoP174 headers.1753. **Single-Retry Nonce Challenge Loop & Workflow Isolation:**176 - If Google's token endpoint returns HTTP `400 Bad Request` with177 `error: "use_dpop_nonce"` and a `"DPoP-Nonce"` response header:178 - **Workflow Isolation:** Google's authorization server enforces179 workflow isolation between authorization code exchange and token180 refresh, returning an HTTP `400 use_dpop_nonce` challenge to181 establish a fresh nonce namespace. This is standard RFC-compliant182 protocol behavior, not a server failure.183 - Cache the fresh nonce in client state (`this.dpopNonce`).184 - Immediately synthesize a new DPoP Proof JWT incorporating the185 updated `nonce` claim and a fresh `jti`.186 - Replay the failed token request **exactly once**. If the retried187 request fails, terminate immediately with an error to prevent188 infinite recursion.189190## 4. Concise Agent Egress Protocol191192When prompted to synthesize or output code deliverables under this skill,193prioritize returning clean, directly importable code blocks without redundant194conversational preambles or repetitive filler. For conceptual or architectural195inquiries, provide standard direct answers.196197## 5. References & Supporting Documentation198199### Developer Documentation (Google for Developers)200- [DPoP Adoption Guide](https://developers.google.com/identity/protocols/oauth2/resources/dpop-adoption) —201 Official Google Identity guide for implementing DPoP across authorization202 code exchange and token refresh.203- [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server#offline) —204 Offline access, refresh tokens, and server-side authorization flows.205- [OAuth 2.0 Best Practices: Sender-Constrain Tokens](https://developers.google.com/identity/protocols/oauth2/resources/best-practices#sender-constrain-tokens) —206 Recommendations for token storage, rotation, and sender-constraining.207208### Developer Knowledge MCP Server209- Agents equipped with Model Context Protocol (`MCP`) can query real-time210 Google Developer documentation using the211 [Google Developer Knowledge MCP Server](https://developers.google.com/knowledge/mcp)212 (`npx -y @google/mcp-developer-knowledge-server`) via213 `developer_knowledge:search_documents` and214 `developer_knowledge:get_documents`.215216### Standards & RFC Specifications217- [RFC 9449: OAuth 2.0 Demonstrating Proof-of-Possession (DPoP)](https://datatracker.ietf.org/doc/html/rfc9449)218- [RFC 7519: JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)219- [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636)