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 冲突时的歧义问题。
解析规则
- 组件名称优先:如果属性名与
Components Object下声明的安全方案名称完全相同,则必须将其视为组件名称。 - URI 引用冲突处理:若要引用一个单段相对 URI 引用(如
foo),且该名称与组件名称(如#/components/securitySchemes/foo)冲突,应使用.路径段(如./foo)来明确引用 URI。 - 不推荐使用 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
评论