OpenAPI 3.2.1 规范更新:支持 OAuth 2.0 Device Flow 与安全元数据发现

OpenAPI 3.2.1 规范于 2026 年 9 月发布,主要更新包括:1) 新增 OAuth 2.0 Device Authorization Flow (RFC 8628) 支持,允许在 `OAuth Flows Object` 中配置 `deviceAuthorization`;2) 新增 `oauth2MetadataUrl` 字段,支持 RFC 8414 元数据发现;3) 新增 `deprecated` 字段,用于标记弃用的安全方案;4) 明确 `Security Requirement Object` 的 URI 引用解析规则,解决组件名称与 URI 冲突问题。这些更新增强了 API 安全机制的描述能力,但要求工具链更新以支持新字段。

READ

OpenAPI 规范(OAS)3.2.1 版本于 2026 年 9 月 10 日发布,在保持与 3.2.x 系列兼容的基础上,重点增强了安全机制的描述能力。该版本引入了对 OAuth 2.0 Device Authorization Flow (RFC 8628) 的原生支持,新增了 oauth2MetadataUrl 字段以支持 RFC 8414 元数据发现,并增加了 deprecated 字段以标记弃用的安全方案。同时,3.2.1 版本对 Security Requirement Object 的 URI 引用解析逻辑进行了更明确的定义,以解决组件名称与 URI 冲突时的歧义问题。

OAuth 2.0 Device Flow 与元数据发现支持

在 3.2.1 版本之前,OpenAPI 规范主要支持 OAuth 2.0 的常见流程(implicit, password, client credentials, authorization code)。3.2.1 版本正式将 OAuth 2.0 Device Authorization Flow (RFC 8628) 纳入规范,允许在 OAuth Flows Object 中配置该流程。

配置示例

在 Security Scheme Object 中,通过 flows 字段添加 deviceAuthorization 配置:

type: oauth2
flows:
  deviceAuthorization:
    deviceAuthorizationUrl: https://example.com/oauth/device
    tokenUrl: https://example.com/oauth/token
    scopes:
      read:data: Read sensitive data
      write:data: Write sensitive data

其中:

  • deviceAuthorizationUrl:设备授权 URL,必须为 TLS 保护的 URL。
  • tokenUrl:令牌 URL,用于设备轮询获取访问令牌。
  • scopes:可用的权限范围。

此外,规范新增了 oauth2MetadataUrl 字段,用于指向 OAuth 2.0 授权服务器的元数据 URL(RFC 8414),支持自动发现授权端点。该字段要求使用 TLS。

type: oauth2
oauth2MetadataUrl: https://example.com/.well-known/oauth-authorization-server
flows:
  authorizationCode:
    authorizationUrl: https://example.com/oauth/authorize
    tokenUrl: https://example.com/oauth/token
    scopes:
      read:data: Read data

安全方案弃用标记

3.2.1 版本引入了 deprecated 布尔字段,允许在 Security Scheme Object 中标记安全方案为已弃用。当 deprecated 设置为 true 时,消费者应避免使用该安全方案。默认值为 false。

type: oauth2
deprecated: true
description: Implicit flow is deprecated. Use Authorization Code with PKCE instead.
flows:
  implicit:
    authorizationUrl: https://example.com/oauth/dialog
    scopes:
      read:data: Read data

这一变更有助于 API 提供者明确标识不再推荐使用的安全机制(如 OAuth Implicit Flow),引导消费者迁移到更安全的方案(如 Authorization Code with PKCE)。

Security Requirement Object 的 URI 引用解析规则

3.2.1 版本对 Security Requirement Object 的 URI 引用解析逻辑进行了更明确的定义,以解决组件名称与 URI 冲突时的歧义问题。

解析规则

  1. 组件名称优先:如果属性名与 Components Object 下声明的安全方案名称完全相同,则必须将其视为组件名称。
  2. URI 引用冲突处理:若要引用一个单段相对 URI 引用(如 foo),且该名称与组件名称(如 #/components/securitySchemes/foo)冲突,应使用 . 路径段(如 ./foo)来明确引用 URI。
  3. 不推荐使用 URI 风格的组件名称:使用看起来像 URI 的安全方案组件名称是不推荐的,因为组件名称匹配优先于 URI 解析,这与直觉相悖。

示例

# 使用组件名称
security:
  - petstore_auth:
      - write:pets
      - read:pets

# 使用 URI 引用(避免与组件名称冲突)
security:
  - ./external_auth:
      - read:data

这一变更旨在提高多文档 OpenAPI 描述中安全方案引用的清晰度和一致性,减少工具链解析时的歧义。

工具链支持与兼容性

OpenAPI 3.2.1 是 3.2.x 系列的补丁版本,旨在修复错误并提供澄清。支持 OAS 3.2 的工具应兼容所有 3.2.* 版本。然而,由于 3.2.1 引入了新的安全机制字段(如 deviceAuthorization、oauth2MetadataUrl、deprecated),旧版工具可能无法正确解析或生成这些字段。

目前,主流代码生成工具(如 OpenAPI Generator)对 3.2.1 新特性的支持情况需查阅其最新文档或 GitHub 仓库。建议在使用 3.2.1 规范时,确保工具链已更新以支持新增的安全机制字段,特别是在涉及 OAuth 2.0 Device Flow 和元数据发现的场景中。

安全考虑

  • TLS 要求:oauth2MetadataUrl、deviceAuthorizationUrl、tokenUrl 和 refreshUrl 均要求使用 TLS。
  • 弃用方案:OAuth Implicit Flow 已被 OAuth 2.0 Security Best Current Practice 建议弃用,推荐使用 Authorization Code Grant with PKCE。
  • 安全过滤:OpenAPI 描述中的 Paths Object 或 Path Item Object 可以为空,以支持访问控制列表(ACL)约束,允许文档提供者精细控制可见性。

参考资料

Conversation

评论

正在加载评论