如何在浏览器与 Node.js 运行时实现 OAuth 2.0 DPoP 刷新令牌发送方绑定

如何在浏览器与 Node.js 运行时实现 OAuth 2.0 DPoP 刷新令牌发送方绑定【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills如果你的应用通过 Google 的 OAuth 2.0 平台保存并使用刷新令牌刷新令牌一旦泄漏攻击者可以拿着它长期换取访问令牌。DPoPRFC 9449Demonstrating Proof-of-Possession的做法是把刷新令牌在密码学上绑定到客户端私有的密钥对只有持有私钥的一方才能完成刷新拦截或重放攻击因此失效。skills 仓库中的 dpop-adoption 技能文档 给出了在浏览器与 Node.js 中实现这一机制的完整实现规范本文按该文档整理出一条可执行路径生成不可提取的 P-256 密钥对、构造 DPoP Proof JWT、向oauth2.googleapis.com/token发起带DPoP头的刷新请求并正确处理use_dpop_nonce挑战。在 Google 的 OAuth 2.0 平台上DPoP 的绑定发生在令牌端点刷新令牌被绑定到密钥对而为 Google API 签发的访问令牌仍是标准 Bearer 令牌token_type: Bearer下游 API 请求不带 DPoP 头。先确认运行环境与适用边界文档对运行时的硬性要求是现代 ES6 JavaScript 模块type: module适用于 Node 18 与浏览器。在这个环境下访问加密能力时必须先验证环境上下文然后直接使用globalThis.crypto。文档明确禁止两种写法因为它们会在混合运行时中造成模块初始化崩溃不要用require(node:crypto)导入遗留 CommonJS 模块不要引用浏览器作用域的window.crypto。另外有一条架构边界需要提前判断纯客户端 SPA没有后端的单页应用无法直接对 Google API 使用 DPoP原因是服务端端点存在client_secret要求且浏览器对DPoP-Nonce响应头有 CORS 限制。文档给出的替代路径是 BFFBackend-for-Frontend模式授权与令牌刷新请求经由 BFF 的服务端客户端完成BFF 设置access_typeoffline、在服务端用 DPoP 绑定刷新令牌并与前端维持安全的会话 Cookie。如果你要保护的是 SPA刷新逻辑应落在 BFF 一侧本文后续步骤都按“代码运行在 Node 18 或浏览器 ES6 模块环境”展开。生成 P-256 密钥对并导出公开 JWK密钥对必须生成在 SECP256R1P-256椭圆曲线上文档给出的算法参数对象是{ name: ECDSA, namedCurve: P-256 }。两个密钥的提取性要求不同这是文档标注的关键安全护栏私钥必须配置为不可提取extractable: false保证私钥永远离开不了硬件密码边界Secure Enclave、Android KeyStore 或 JS 沙箱内存以此抵御 XSS 和依赖令牌窃取攻击公钥必须保持可导出extractable: true用于输出 JSON Web KeyJWK。导出公钥 JWK 时文档要求构造一个“干净的 JWK 字典”严格只包含以下字段kty: ECcrv: P-256xBase64URL 编码的 x 坐标去掉末尾的填充yBase64URL 编码的 y 坐标去掉末尾的填充同时明确禁止暴露私钥参数d或任何多余元数据。DPoP Proof JWT 的请求头里要嵌入的就是这个 JWK。构造刷新请求用的 DPoP Proof JWTDPoP Proof JWT 由请求头、Payload 和签名三部分组成。文档把生成逻辑集中要求实现到createDPoPProof中其必选的公开接口契约原文签名如下// 1. Key generation JWK export export async function generateDPoPKeyPair() // - { publicKey, privateKey } (private key extractablefalse) 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 }文档说明要求模块显式导出以上全部函数目的是能顺利接入 CI/CD 校验框架和自动化探针。如果你是在检查或重构已有代码库要确认等价的密码学与 RFC 9449 逻辑存在。请求头Header文档给出的 JOSE 头部typ、alg、jwk如下// Header { typ: dpopjwt, alg: ES256, jwk: await exportPublicJWK(publicKey) }Payload 字段推导规则刷新请求以及授权码交换请求的 Payload 各字段取值规则如下字段取值规则htm大写 HTTP 方法令牌请求固定为POSThtu用sanitizeHTU(htu)去掉查询参数和 hash 后的目标 URI令牌请求即https://oauth2.googleapis.com/tokeniat当前整型纪元秒时间戳Math.floor(Date.now() / 1000)jti按下方三级优先级推导ath可选仅当提供了accessToken参数RFC 9449 资源请求场景时计算base64url(sha256(accessToken))并注入RFC 9449 Section 6.1nonce可选提供nonce参数时直接注入 Payloadjti是文档标注的关键不变量推导有严格优先级如果向createDPoPProof显式传入了jti参数优先使用这个精确字符串否则如果传入了authCode参数初次授权码交换场景则jti await calculateAuthCodeJti(authCode)其中calculateAuthCodeJti计算base64url(sha256(authCode))使 Proof 与授权码密码学绑定两者都没有时生成新的加密随机字符串文档示例为crypto.getRandomValues(new Uint8Array(24))后做 base64url 编码。对于刷新请求既没有显式jti也没有authCode走第 3 条每次刷新生成一个新的随机jti。注意后文 nonce 重试时也要求 freshjti。htu的清洗实现文档直接给出const u new URL(htu); return ${u.origin}${u.pathname};签名输出格式对 WebCrypto 结果不要做 DER 转换DPoP Proof JWT 要求按 IEEE P1363 和 RFC 7518 输出原始拼接坐标签名R || SP-256 下恰好 64 字节。这里有一个容易踩的坑在标准 WebCryptocrypto.subtle.sign下ECDSA 签名天然就是 raw IEEE P1363 格式32 字节r与 32 字节s拼接共 64 字节。不要对crypto.subtle.sign的输出做 DER 到 Raw 的转换——把 64 字节的 raw 缓冲当作 ASN.1 DER 解析会立刻抛出运行时异常Invalid DER sequence。正确做法是直接对 raw ArrayBuffer 做 base64url 编码。仅当在遗留 Java/Androidjava.security.Signature或 Node CommonJScrypto.createSign中实现时才需要把 ASN.1 DER 输出先转换成 raw 64 字节 IEEE P1363 格式再做 base64url 编码。浏览器和 Node 18 ES6 模块都属于 WebCrypto 原生路径走第一种即可。向令牌端点发起刷新请求令牌端点请求的工作方式由文档第 3 节规定对POST请求授权码交换grant_typeauthorization_code与令牌刷新grant_typerefresh_token把 DPoP Proof JWT 放在DPoPHTTP 头中发送// POST https://oauth2.googleapis.com/token // grant_typerefresh_token刷新或 grant_typeauthorization_code授权码交换 headers: { DPoP: ${proofJwt} }刷新成功后令牌端点返回的访问令牌是token_type: Bearer。之后对 Google API如 Calendar、Drive、Gmail的下游请求使用标准Authorization: Bearer ${accessToken}头不带 DPoP 头——发送方绑定只约束令牌端点上的刷新操作。处理 400 use_dpop_nonce 挑战当令牌端点返回 HTTP400 Bad Request、error: use_dpop_nonce且响应头带有DPoP-Nonce时文档明确说明这不是服务端故障Google 的授权服务器会在授权码交换与令牌刷新两个工作流之间执行 workflow isolation通过400 use_dpop_nonce挑战建立新的 nonce 命名空间这是符合 RFC 的标准协议行为例如一个原本用于授权码交换的客户端首次发起刷新时就会遇到。文档规定的处理流程是“单次重试”把新的 nonce 缓存到客户端状态文档示例字段为this.dpopNonce立即重新合成一个 DPoP Proof JWTPayload 中带上更新后的nonceclaim 和一个新的jti把失败的令牌请求原样重放且只允许重放一次如果重试仍然失败立即以错误终止防止无限递归。流程示意依据文档规则整理// 第一次刷新请求收到 400 use_dpop_nonce 后 if (status 400 error use_dpop_nonce) { this.dpopNonce headers.get(DPoP-Nonce); // 用新 nonce 新 jti 重新合成 Proof proofJwt await createDPoPProof({ privateKey, publicKey, htm, htu, nonce: this.dpopNonce }); // 重放一次再次失败则直接抛错退出不再循环 }验证verifyDPoPProof 与成功信号文档把验证路径也写进了强制导出契约verifyDPoPProof(dpopProofJwt)返回{ isValid: boolean, header, payload, error }。实现完成后可以对生成的 Proof JWT 调用该函数检查isValid并在error存在时定位是头部、Payload 还是签名环节出了问题。运行时的验证信号有两个令牌端点对带DPoP头的刷新请求正常返回令牌且返回体中token_type为Bearer说明绑定流程走通访问令牌可照常用于下游 API若出现use_dpop_nonce按上一节的单次重试流程处理后应能通过重试第二次仍失败时按文档要求以错误终止不要进入循环重试。边界与限制文档列出的限制在实现时需要遵守私钥一旦可提取extractable: true就破坏了非可提取安全护栏DPoP 的防窃取价值不成立实现密钥生成时两个密钥的提取性不要配反。纯客户端 SPA 直接对 Google API 使用 DPoP 不可行client_secret要求与DPoP-Nonce响应头的浏览器 CORS 限制需按 BFF 模式把刷新逻辑放到服务端。不要给下游 Google API 请求附加 DPoP 头访问令牌是标准 Bearer 令牌只有令牌端点的两个 POST 场景授权码交换、刷新需要DPoP头。WebCrypto 环境的签名输出已是 raw IEEE P1363对crypto.subtle.sign结果做 DER 解析会在运行时直接抛Invalid DER sequence。完整实现规范含所有导出签名与推导规则见 skills/identity/dpop-adoption/SKILL.md其中还列出了 RFC 9449、RFC 7519、RFC 7636 及 Google Identity 官方 DPoP 指南的出处可按需核对。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考