secure-oauth-oidc

安全的 OAuth 和 OpenID Connect

应将 OAuth 安全视为一组端到端协议不变量，而不是参数检查清单。以 RFC 9700 / BCP 240 为基线，再补充所选 OAuth 扩展、OpenID Connect、平台配置文件和部署的要求。

OAuth 用于委托访问权限。OpenID Connect 增加了身份验证。绝不要仅凭 OAuth 推断登录身份，也绝不要将访问令牌用作 ID Token。

本技能负责 OAuth/OIDC 协议层。对于最终面向浏览器的 BFF 应用会话——包括会话 Cookie、CSRF 和浏览器请求策略、公共/受保护端点分类，以及防止令牌暴露给浏览器——请加载 bff-entry-points 技能。

将你接触的流程提升至基线要求

任何新增、扩展、重新路由或重新指向授权码流程部分的更改，都应在同一更改中将该流程的整个事务提升至 RFC 9700 基线：使用 S256 PKCE，并为每笔事务设置独立的 verifier；使用全新的一次性 state，并在 OIDC 中使用 nonce；二者都必须绑定到发起登录的浏览器；精确匹配重定向 URI；验证所使用的每个令牌的颁发者和受众；并且不得将任何令牌放入 URL、日志或浏览器可读取的任何内容中。

措辞狭窄的请求、仓库中的待办清单或交接说明、固定当前实现形态的现有测试，或缺陷早于你加入项目这一事实，都不代表可以让该流程低于基线要求。不要为了匹配旁边不安全的流程而构建新流程，也不要让你正在编辑的文件或函数继续存在暴露风险。只能将本次更改未涉及的内容列为剩余风险。

加载合适的参考资料

参考资料	加载时机
references/rfc9700-control-catalog.md	进行安全设计或审查时始终加载；该资料保留了要求的强度、适用范围和章节出处
references/attack-and-test-catalog.md	进行威胁建模、事件分析、对抗性审查或编写否定测试时
references/oidc-validation.md	处理任何 OIDC、ID Token、UserInfo、Discovery、多颁发者或联合登录工作时
references/review-and-delivery.md	审计实现、报告问题、规划修复或定义完成证据时
references/standards-map.md	选择扩展/配置文件、解决来源优先级问题，或检查标准是否稳定且为当前版本时

只阅读任务所需的参考资料。当控制目录提供了规范性原文时，不要依赖记忆。

首先确定安全配置

在推荐代码或配置之前，先明确：

1. 目标 — 委托 API 访问、用户身份验证、两者兼有、机器对机器访问、设备授权，还是令牌交换。
2. 参与方 — 授权服务器 / OpenID Provider、客户端 / 依赖方、资源服务器、资源所有者 / 最终用户、浏览器或系统用户代理，以及终止 TLS 的中间设备。
3. 客户端类型和执行环境 — 机密客户端还是公共客户端；服务端 Web 应用、浏览器应用、原生应用、服务、CLI 或设备。应根据凭据实际上能否保密来分类，而不是依据注册标签。
4. 流程和响应模式 — 列出所有已启用的授权类型、响应类型、响应模式、回调、令牌交换、刷新路径、注销路径和后端调用，包括旧版路径。
5. 信任拓扑 — 单一发行方还是多个；静态还是动态发现 / 注册；一个还是多个资源服务器；同一方还是第三方组件；代理和服务网格。
6. 适用配置文件 — RFC 9700 基线，以及 OIDC Core、原生应用 BCP、DPoP、mTLS、PAR/JAR/JARM、FAPI 或其他部署配置文件。更严格的配置文件会增加要求，不会取代基线。
7. 证据 — 确切的代码、配置、元数据、库及版本、测试和运行时行为。将所有未检查的内容标记为未知。

如果任务描述不充分，应先检查代码库和已部署的元数据。只有在相关选择会实质性改变配置文件，且无法安全地自行查明时，才询问用户。

建立事务台账

从发起开始，跟踪每个流程直到回调、令牌使用、刷新、撤销和注销。记录每项工件的创建、存储、传输、验证、使用、过期和失效责任方：

工件	必需的绑定或验证
授权请求	预期的发行方、客户端、精确的重定向 URI、响应类型 / 模式、请求的资源和权限
state	高熵、一次性，并安全绑定到发起流程的用户代理会话；携带应用状态时须进行完整性保护
PKCE 验证码 / 挑战	与事务相关；由发起请求的客户端实例保留验证码机密；使用 S256；授权服务器记录是否存在挑战
OIDC nonce	与事务相关，并绑定到发起会话；在使用任何返回的令牌之前，先在正确的 ID Token 中验证
授权响应	预期的会话、发行方、重定向端点、响应模式，以及错误 / 成功语义
授权码	客户端、重定向 URI、事务 / PKCE 挑战、单次使用、短有效期
访问令牌	发行方、预期资源 / 受众、权限、有效期、令牌类型，以及受约束时的发送方密钥
刷新令牌	客户端实例、授权、已同意的范围 / 资源、重放检测系列或发送方密钥、过期 / 撤销状态
ID Token	预期发行方、依赖方受众、签名 / 算法、时间声明、nonce 和特定于流程的哈希值

缺失或隐式的绑定，正是混淆攻击、CSRF、授权码注入、令牌替换和重放攻击的藏身之处。

应用 RFC 9700 基线

准确措辞和条件适用性请参阅控制目录。至少应核实以下边界：

重定向与授权边界

• 要求与预先注册的重定向 URI 进行精确字符串匹配。仅允许 RFC 8252 定义的原生环回端口例外；不得将其扩展到主机、路径、方案或其他客户端。
• 在客户端和授权服务器两端都拒绝开放重定向器。
• 除范围严格限定的原生环回情形外，绝不通过未加密连接发送授权响应。
• 使用与事务绑定的机制防止 CSRF。只有在确认支持 PKCE 后，才能仅依靠 PKCE 承担此责任；否则使用一次性、与会话绑定的 state，或在其保证适用时使用 OIDC nonce。
• 对于使用多个发行方的客户端，将选定的发行方绑定到用户代理会话，并在授权响应中验证发行方。优先使用 RFC 9207 iss 或等效的签名响应；不同的重定向 URI 是备用方案。
• 凭据表单提交后不得使用 HTTP 307；HTTP 重定向应使用 303。

授权码边界

• 公共客户端必须使用 PKCE，并建议机密客户端使用 PKCE。除非适用的配置文件另有规定，否则所有授权码客户端都默认使用 PKCE。
• 使用 S256，确保验证器和挑战值各自绑定到特定事务，强制验证验证器；如果授权请求中没有挑战值，则拒绝提供验证器的令牌请求。
• 授权码应设为短时有效且只能使用一次。将第二次兑换视为泄露信号；授权服务器 SHOULD 撤销此前基于该授权码签发的所有令牌。
• 不要误以为客户端身份验证可以防止授权码注入；合法的机密客户端仍可能兑换被注入的授权码。

令牌边界

• 不得使用资源所有者密码授权。避免使用隐式授权，或任何会从授权端点返回访问令牌的响应，除非能够证明已缓解所有明确指出的注入和泄露途径。
• 绝不将访问令牌放在 URI 查询参数中。
• 按资源/受众和最小权限原则限制访问令牌；要求每个资源服务器都强制执行这两项限制。
• 优先使用 DPoP 或 mTLS 实施发送方约束访问令牌。资源服务器必须验证令牌绑定和证明；仅持有已绑定的令牌并不足够。
• 对于公共客户端，应对刷新令牌实施发送方约束，或在轮换令牌时检测重复使用。将每个刷新令牌绑定到已同意的范围和资源服务器。
• 在存储、传输、日志、跟踪记录、错误信息、URL、分析数据和测试夹具中，都应将令牌视为机密。不得对存储安全作出超出适用平台/配置文件支持范围的绝对声明；应说明相关威胁和依据。

部署边界

• 发布并使用授权服务器元数据；验证发行方，且不得混用不同发行方的端点或密钥。
• 在终止 TLS 的代理处，删除或覆盖攻击者提供的安全标头，并保护代理到应用程序之间的链路，防止窃听、注入和重放。
• 通过 CSP frame-ancestors 和适当的兼容性防护，防止授权、登录、同意、设备及错误页面遭受点击劫持。
• 避免在授权和回调页面中加载可能接收 Referer 数据的第三方资源；应设置明确的 Referrer Policy。
• 对于 postMessage 流程，应使用精确注册的目标来源，绝不使用 *，精确验证发送方来源，并应用所有常规授权响应控制措施。
• 不得在授权端点启用 CORS。CORS 不是 OAuth CSRF 防护措施。

添加 OIDC 身份层

处理 OIDC 工作时，请加载 references/oidc-validation.md，并将以下三个关注点分开：

• state 用于关联授权响应，并保护客户端回调。
• PKCE 将授权码绑定到发起请求的客户端实例；在确认支持的情况下，也可以防范 CSRF。
• nonce 将 ID Token 绑定到一次身份验证事务，并且在符合 RFC 9700 所述条件时，可以保护机密 OIDC 客户端免受代码注入攻击。

应将 ID Token 作为协议对象进行验证，而不只是将其视为已签名的 JWT。将本地账户绑定到 (iss, sub)，验证依赖方受众和授权方，强制执行时间和 nonce 语义，按需验证特定流程的令牌哈希，并要求 UserInfo 中的 sub 与 ID Token 中的 sub 一致。

除非特定访问令牌配置文件明确规定了受支持的契约，否则客户端不得解析访问令牌来获取身份信息。即使 JWT 访问令牌有效，它面向的也是资源服务器，而非依赖方。

选择任务路径

设计或迁移

1. 制定安全配置文件以及信任边界图或流程跟踪记录。
2. 说明每项事务绑定和令牌验证不变量。
3. 在添加可选的强化措施之前，先移除不安全的授权类型。
4. 选择可互操作的控制措施，并依据最新的一手文档确认提供方和库的支持情况。
5. 在实现之前定义负向测试和可观测性要求。
6. 对于迁移，清点所有客户端和回调，有计划地分阶段处理兼容性，定义回滚方案，并为任何较弱的过渡模式设定时间限制。

实现

1. 使用受维护的 OAuth/OIDC 库，而不是自行实现协议或密码学。
2. 检查确切的库版本和配置路径；默认值和方法名称并不能作为依据。
3. 在信任边界处执行验证，并在创建会话或转发令牌之前以失败关闭方式处理。
4. 不要将机密和原始令牌写入遥测数据。应改为记录安全标识符、决策原因、颁发者、客户端 ID、受众、授权类型和重放事件。触及包含记录或返回原始令牌、授权码或验证器的文件时，应立即删除相应代码行——你绕过不处理的暴露问题，最终仍会随代码一并交付——并且绝不要编写断言令牌出现在 URL、响应正文或日志中的测试。
5. 添加行为驱动的正向和负向测试。更改生产代码时，应尽可能采用代码库的测试/TDD 工作流。

审查或事件诊断

1. 从攻击者能力追踪攻击路径，直到相关资产和影响；未经验证适用性，不要仅因缺少参数就报告问题。
2. 区分规范性不合规、可利用的弱点、纵深防御缺口和未知。
3. 提供文件/行号、配置路径、元数据字段、HTTP 跟踪记录或可复现的场景作为证据。对所有凭据和令牌值进行脱敏。
4. 处理事件期间，应保全证据，遏制令牌/授权码/凭据泄露，撤销受影响的授权或令牌族，轮换已泄露的密钥，然后修复导致问题的控制措施。不要销毁证据，也不要探测授权范围之外的系统。
5. 使用 references/review-and-delivery.md 作为报告和完成标准。

不要轻信虚假的安全保证

• 仅仅存在 state 并不能提供保护，除非它不可预测、只能使用一次、经过验证，并且与发起请求的会话绑定。
• PKCE 不是客户端身份验证，不会验证发行方，也无法修复任意授权请求篡改。
• OIDC nonce 不是通用的纯 OAuth 防护，也无法阻止窃贼兑换被盗的公共客户端授权码。
• TLS 无法阻止端点混淆、浏览器历史记录泄露、Referer 泄露、开放重定向或端点被攻陷。
• 有效的 JWT 签名不能证明发行方、受众、令牌类型、新鲜度、nonce 或授权符合预期。
• 如果攻击者同时获得令牌和可用的密钥材料，DPoP 或 mTLS 就无济于事；XSS 或客户端被攻陷也可能使这一安全边界失效。
• CORS、SameSite Cookie、浏览器代码中的客户端密钥以及隐藏参数，都不能替代协议绑定。
• 提供方的成功顺畅流程不能作为安全证据。应测试恶意重定向、重放、发行方替换和验证失败。

交付约定

请提供：

1. 范围与配置 —— 参与方、客户端类型、流程、发行方、资源以及采用的标准。
2. 流程与信任边界 —— 令牌等产物的绑定关系及验证点。
3. 发现的问题或设计决策 —— 要求强度、证据、攻击场景、修复措施和验证方式。
4. 已满足的控制项 —— 仅列出有证据支持的项。
5. 未知项与假设 —— 不得在缺少证据时默认为符合要求。
6. 测试与运行时检查 —— 覆盖正向、负向、重放和故障路径。
7. 剩余风险与迁移限制 —— 明确列出例外、负责人和到期日期。

不能仅因为所有顺畅流程测试都通过，或所有检查清单项都已填写，就宣称 OAuth/OIDC 系统安全。只能声明已检查的证据所能证明的内容。