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 hardware cryptographic boundary (Secure Enclave, Android
KeyStore, or JS sandbox memory), thwarting XSS and dependency token theft
attacks.
- 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---2description: Implement and debug OAuth 2.0 DPoP (RFC 9449) refresh token sender-constraining for WebCrypto, Node.js ES6, and browser runtimes integrating with Google's OAuth platform. Use when configuring non-extractable asymmetric key pairs (P-256), generating DPoP Proof JWTs for authorization code exchange and token refresh, or handling 400 use_dpop_nonce challenge retry loops at oauth2.googleapis.com/token. Don't use for unconstrained OAuth 2.0 flows (where refresh tokens are not bound to a client key pair), or for Google Cloud IAM / service account authentication.3metadata:4 source: https://skillmd.com/skills/h3y6e/dpop-adoption5 category: Identity6 github-path: skills/identity/dpop-adoption7 github-ref: refs/heads/main8 github-repo: https://github.com/google/skills9 github-tree-sha: 8d2c0ff3aad88a8bc875e01a7d99b3d3dd4673d910 version: 1.0.011name: dpop-adoption12---1314# DPoP Adoption & Identity Security Architecture1516Demonstrating Proof-of-Possession (DPoP, RFC 9449) secures OAuth 2.0 refresh17tokens against interception and replay attacks by cryptographically binding them18to a private key held exclusively by the client. In Google's OAuth 2.0 platform,19DPoP binds the refresh token at the token endpoint, while access tokens issued20for Google APIs are standard Bearer tokens (`token_type: "Bearer"`).2122## 1. Core Cryptographic & Architectural Invariants2324When implementing DPoP helpers or upgrading HTTP clients, you MUST adhere to the25following strict security invariants:2627### A. Universal WebCrypto & Runtime Compatibility2829- In modern ES6 JavaScript (`"type": "module"` for Node 18+ and browsers),30 ALWAYS access `globalThis.crypto` directly after verifying the environment31 context.32- **NEVER** import legacy CommonJS modules via `require('node:crypto')` or33 reference browser-scoped `window.crypto`, as these cause module34 initialization crashes across hybrid runtimes.3536### B. Hardware-Backed Non-Extractable Key Persistence3738- Generate an Elliptic Curve key pair on the SECP256R1 (`P-256`) curve: `{39 name: 'ECDSA', namedCurve: 'P-256' }`.40- **CRITICAL SECURITY GUARDRAIL:** The private key MUST be configured as41 **non-extractable** (`extractable: false`). This guarantees the private key42 can never leave the hardware cryptographic boundary (Secure Enclave, Android43 KeyStore, or JS sandbox memory), thwarting XSS and dependency token theft44 attacks.45- The public key MUST remain exportable (`extractable: true`) to allow46 emitting JSON Web Keys (JWKs).4748### C. Public JWK Formatting Standards4950- When exporting public keys to attach to DPoP Proof JWT headers, construct a51 clean JWK dictionary containing strictly:52 - `"kty": "EC"`53 - `"crv": "P-256"`54 - `"x"`: Base64URL-encoded x-coordinate without trailing equal sign55 padding (`=`).56 - `"y"`: Base64URL-encoded y-coordinate without trailing equal sign57 padding (`=`).58- **NEVER** expose private key parameters (`"d"`) or superfluous metadata.5960### D. IEEE P1363 vs. ASN.1 DER Signature Disambiguation6162- DPoP Proof JWTs require raw concatenated coordinate signatures ($R \parallel63 S$, exactly 64 bytes for P-256) per IEEE P1363 and RFC 7518.64- **WebCrypto Native Rule:** In standard WebCrypto (`crypto.subtle.sign`),65 ECDSA signatures are ALREADY emitted natively in raw IEEE P1363 format66 (concatenated 32-byte `r` and `s` buffers, 64 bytes total). **DO NOT**67 attempt DER-to-Raw conversion on `crypto.subtle.sign` outputs, as parsing a68 64-byte raw buffer as ASN.1 DER causes an immediate runtime exception69 (`Invalid DER sequence`). Directly base64url-encode the raw ArrayBuffer.70- **Legacy API Fallback:** If and only if implementing in legacy Java/Android71 (`java.security.Signature`) or Node CommonJS (`crypto.createSign`), convert72 ASN.1 DER output to raw 64-byte IEEE P1363 format before base64url encoding.7374### E. SPA & Backend-for-Frontend (BFF) Architecture7576- **Secretless SPAs Limitation:** Pure client-side single-page applications77 (SPAs) without a backend cannot use DPoP directly with Google APIs due to78 `client_secret` requirements on server endpoints and browser CORS79 limitations on the `DPoP-Nonce` response header.80- **BFF Pattern:** To secure SPAs with DPoP, route authorization and token81 refresh requests through a Backend-for-Frontend (BFF) server-side client.82 The BFF sets `access_type=offline`, binds refresh tokens server-side using83 DPoP, and maintains secure session cookies with the frontend.8485## 2. Implementation Rules & Mandatory Public API8687When creating new modules, your module MUST explicitly export all functions88below to integrate cleanly with CI/CD verification harnesses and automated89probers. When inspecting or refactoring existing codebases, ensure equivalent90cryptographic and RFC 9449 logic is present. Obey strict claim derivation logic91in all cases:9293### A. DPoP Proof JWT Claim Derivation Rules (`createDPoPProof`)9495When generating the DPoP Proof JWT in `createDPoPProof`:9697**1. JOSE Header (`typ`, `alg`, `jwk`):**98```javascript99// Header100{101 "typ": "dpop+jwt",102 "alg": "ES256",103 "jwk": await exportPublicJWK(publicKey)104}105```106107**2. Payload Claims:**108- `"htm"`: Uppercase HTTP Method (`"POST"` for token requests).109- `"htu"`: Target URI stripped of query parameters and hash fragments using110 `sanitizeHTU(htu)`. For token requests, this is111 `https://oauth2.googleapis.com/token`.112- `"iat"`: Current integer epoch timestamp in seconds113 (`Math.floor(Date.now() / 1000)`).114- `"jti"` (Critical Invariant):115 1. If an explicit `jti` argument is provided to `createDPoPProof`, use that116 exact string over all others.117 2. Otherwise, if an `authCode` argument is provided (during initial code118 exchange), set `jti = await calculateAuthCodeJti(authCode)` where119 `calculateAuthCodeJti` computes `base64url(sha256(authCode))` to ensure120 the DPoP proof is cryptographically bound to the authorization code.121 3. Only if neither `jti` nor `authCode` is provided, generate a fresh122 cryptographic random string via `generateRandomString()` (such as123 `crypto.getRandomValues(new Uint8Array(24))` base64url encoded).124- `"ath"` (Optional): If an `accessToken` argument is provided for RFC 9449125 resource requests, compute `base64url(sha256(accessToken))` via126 `calculateATH(accessToken)` and inject it (RFC 9449 Section 6.1).127- `"nonce"` (Optional): If a `nonce` argument is provided, inject it directly128 into the payload.129130### B. Explicit Export Signatures131132```javascript133// 1. Key generation & JWK export134export async function generateDPoPKeyPair() // -> { publicKey, privateKey } (private key extractable=false)135export async function exportPublicJWK(publicKey) // -> { kty: 'EC', crv: 'P-256', x, y }136137// 2. Proof generation & validation138export async function createDPoPProof({ privateKey, publicKey, htm, htu, nonce, accessToken, authCode, jti }) // -> signed JWT string139export async function verifyDPoPProof(dpopProofJwt) // -> { isValid: boolean, header, payload, error }140export function sanitizeHTU(htu) // -> URL stripped of query and hash: const u = new URL(htu); return `${u.origin}${u.pathname}`;141142// 3. Cryptographic & encoding utilities143export function base64UrlEncode(buffer) // -> Uint8Array/ArrayBuffer to base64url string without '=' padding144export function base64UrlDecode(str) // -> base64url string to Uint8Array/Buffer145export function stringToBase64Url(str) // -> UTF-8 string to base64url146export function base64UrlToString(str) // -> base64url to UTF-8 string147export function generateRandomString(byteLength = 32) // -> cryptographic random base64url string148export async function calculateATH(accessToken) // -> base64url(sha256(accessToken)) per RFC 9449 Sec 6.1149export async function calculateAuthCodeJti(code) // -> base64url(sha256(code))150export async function generatePKCE() // -> { codeVerifier (>=43 chars), codeChallenge, codeChallengeMethod: 'S256' }151```152153## 3. Token Endpoint & Resource Request Workflow154155When integrating with Google's OAuth 2.0 platform:1561571. **Token Endpoint Requests (`oauth2.googleapis.com/token`):**158 - Attach the DPoP Proof JWT in the `DPoP` HTTP header:159 `` `DPoP: ${proofJwt}` `` when making `POST` requests for code exchange160 (`grant_type=authorization_code`) and token refresh161 (`grant_type=refresh_token`).1622. **Resource API Requests:**163 - Google's token endpoint returns `"token_type": "Bearer"`. Downstream164 requests to Google APIs (e.g. Calendar, Drive, Gmail) use standard165 `` `Authorization: Bearer ${accessToken}` `` headers without DPoP166 headers.1673. **Single-Retry Nonce Challenge Loop & Workflow Isolation:**168 - If Google's token endpoint returns HTTP `400 Bad Request` with169 `error: "use_dpop_nonce"` and a `"DPoP-Nonce"` response header:170 - **Workflow Isolation:** Google's authorization server enforces171 workflow isolation between authorization code exchange and token172 refresh, returning an HTTP `400 use_dpop_nonce` challenge to173 establish a fresh nonce namespace. This is standard RFC-compliant174 protocol behavior, not a server failure.175 - Cache the fresh nonce in client state (`this.dpopNonce`).176 - Immediately synthesize a new DPoP Proof JWT incorporating the177 updated `nonce` claim and a fresh `jti`.178 - Replay the failed token request **exactly once**. If the retried179 request fails, terminate immediately with an error to prevent180 infinite recursion.181182## 4. Concise Agent Egress Protocol183184When prompted to synthesize or output code deliverables under this skill,185prioritize returning clean, directly importable code blocks without redundant186conversational preambles or repetitive filler. For conceptual or architectural187inquiries, provide standard direct answers.188189## 5. References & Supporting Documentation190191### Developer Documentation (Google for Developers)192- [DPoP Adoption Guide](https://developers.google.com/identity/protocols/oauth2/resources/dpop-adoption) —193 Official Google Identity guide for implementing DPoP across authorization194 code exchange and token refresh.195- [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server#offline) —196 Offline access, refresh tokens, and server-side authorization flows.197- [OAuth 2.0 Best Practices: Sender-Constrain Tokens](https://developers.google.com/identity/protocols/oauth2/resources/best-practices#sender-constrain-tokens) —198 Recommendations for token storage, rotation, and sender-constraining.199200### Developer Knowledge MCP Server201- Agents equipped with Model Context Protocol (`MCP`) can query real-time202 Google Developer documentation using the203 [Google Developer Knowledge MCP Server](https://developers.google.com/knowledge/mcp)204 (`npx -y @google/mcp-developer-knowledge-server`) via205 `developer_knowledge:search_documents` and206 `developer_knowledge:get_documents`.207208### Standards & RFC Specifications209- [RFC 9449: OAuth 2.0 Demonstrating Proof-of-Possession (DPoP)](https://datatracker.ietf.org/doc/html/rfc9449)210- [RFC 7519: JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)211- [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636)