A2A SecurityScheme：声明客户端如何认证

A2A Agent Card 本身不做任何认证，它只声明认证方式：securitySchemes 定义有名称的认证方法，securityRequirements 说明客户端必须满足其中哪些。客户端从 Agent Card 读取这两部分，通过带外方式获取凭据，并在每个请求中携带。服务器必须认证每一个收到的请求。

本页讲对象本身。运行时的规则，例如授权范围控制和任务内授权，见认证、授权与安全注意事项。

三个字段，三项职责

位置	字段	类型	职责
Agent Card	`securitySchemes`	名称到 `SecurityScheme` 的映射	用您自定的名称定义接受的方法
Agent Card	`securityRequirements`	`SecurityRequirement` 列表	说明客户端必须满足哪些已定义的方案及 scope
`AgentSkill`	`securityRequirements`	`SecurityRequirement` 列表	同上，作用于单个技能（见 AgentSkill ）

SecurityRequirement 只有一个字段 schemes：把方案名称映射到 { "list": [...] }，即所需 scope 的列表。下面是规范的示例卡片，它定义了一个名为 google 的 OpenID Connect 方案，并要求以三个 scope 使用它：

"securitySchemes": {
  "google": {
    "openIdConnectSecurityScheme": {
      "openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
    }
  }
},
"securityRequirements": [{ "schemes": { "google": { "list": ["openid", "profile", "email"] } } }]

规范没有说明 securityRequirements 中的多个条目如何组合，因此不要仅凭结构就假定是 AND 或 OR 语义。

五种方案类型

SecurityScheme 是基于 OpenAPI 3.2 Security Scheme Object 的可辨识联合（protobuf 的 oneof）。securitySchemes 中的每一项只设置下列键之一：

JSON 键	必填字段	可选字段
`apiKeySecurityScheme`	`location`（`query`、`header` 或 `cookie`）和 `name`（参数名称）	`description`
`httpAuthSecurityScheme`	`scheme`（RFC 7235 的方案名称，如 `Bearer`，应登记在 IANA 注册表中）	`bearerFormat`（例如 `JWT`，仅作说明）和 `description`
`oauth2SecurityScheme`	`flows`	`oauth2MetadataUrl`（RFC 8414 授权服务器元数据，要求 TLS）和 `description`
`openIdConnectSecurityScheme`	`openIdConnectUrl`（OpenID Connect Discovery URL）	`description`
`mtlsSecurityScheme`	无	`description`

规范只给出了 OpenID Connect 的 JSON 示例。下面的片段是示意性的：依据上表中的 proto 字段名构造，并非摘自官方文档，展示的是 HTTP Bearer 方案。

"securitySchemes": {
  "bearerAuth": {
    "httpAuthSecurityScheme": { "scheme": "Bearer", "bearerFormat": "JWT" }
  }
},
"securityRequirements": [{ "schemes": { "bearerAuth": { "list": [] } } }]

OAuth 2.0 流程

OAuthFlows 同样是 oneof：oauth2SecurityScheme 在 flows 下设置一种流程。v1.0.1 的 proto 中：

JSON 键	必填字段	可选字段	状态
`authorizationCode`	`authorizationUrl`、`tokenUrl`、`scopes`	`refreshUrl`、`pkceRequired`	现行
`clientCredentials`	`tokenUrl`、`scopes`	`refreshUrl`	现行
`deviceCode`	`deviceAuthorizationUrl`、`tokenUrl`、`scopes`	`refreshUrl`	现行；面向 CLI 工具和输入受限设备（RFC 8628）
`implicit`	未标注	`authorizationUrl`、`refreshUrl`、`scopes`	已弃用：“请改用 Authorization Code + PKCE”
`password`	未标注	`tokenUrl`、`refreshUrl`、`scopes`	已弃用：“请改用 Authorization Code + PKCE 或 Device Code”

scopes 把 scope 名称映射到简短说明。pkceRequired 表示该流程是否强制使用 PKCE（RFC 7636）；proto 补充说明：公共客户端应始终使用 PKCE，并建议所有客户端都使用。

下面第二个示意性片段声明了强制 PKCE 的 Authorization Code 流程。URL 是占位符，scope 取自迁移指南自己的示例。

"securitySchemes": {
  "oauth": {
    "oauth2SecurityScheme": {
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://auth.example.com/authorize",
          "tokenUrl": "https://auth.example.com/token",
          "pkceRequired": true,
          "scopes": { "read": "Read access" }
        }
      }
    }
  }
},
"securityRequirements": [{ "schemes": { "oauth": { "list": ["read"] } } }]

官方资料中的三个陷阱

旧示例仍然存在。 规范 v1.0.1 标签中的示例卡片，仍以 v0.3 的写法书写要求："security": [{ "google": ["openid", "profile", "email"] }]。官方仓库在发布之后修正了它（2026 年 7 月，拉取请求 #2046），本页使用的是 a2a.proto 为 v1.0 定义的形式。如果您从较旧的规范副本复制卡片，请先检查这个字段。

JSON 键遵循 proto 字段名。 规范要求 JSON 名称使用由 proto 字段名转换而来的 camelCase（第 5.5 节）。v1.0 迁移指南中的 OAuth 示例写的是 authorizationCodeFlow 和 implicitFlow，而 proto 字段是 authorization_code 和 implicit，所以键应为 authorizationCode 和 implicit，如上表所示。各来源不一致时，规范明确 proto 是"唯一权威的规范性定义"（第 1.4 节）。

“已移除"的流程仍在 proto 中。 迁移指南把 ImplicitOAuthFlow 和 PasswordOAuthFlow 列为已移除。v1.0.0 与 v1.0.1 的 proto 仍把它们声明为 OAuthFlows 的 3 号和 4 号成员，并标记为 deprecated，规范第 4.5 节只记录了三种现行流程。新卡片请不要声明 Implicit 或 Password 流程；解析其他智能体的卡片时，把它们视为已弃用而不是不存在。

从 v0.3 升级？

以下是 v0.3.0 与 v1.0.1 两个 a2a.proto 之间的差异：

变化	说明
`Security` 重命名	现为 `SecurityRequirement`，结构相同。`AgentCard.security` 变为 `securityRequirements`（9 号字段），`AgentSkill.security` 变为 `securityRequirements`（8 号字段）
新增 Device Code 流程	`OAuthFlows.device_code`（5 号字段），对应 `DeviceCodeOAuthFlow`
新增 PKCE 标志	`AuthorizationCodeOAuthFlow.pkce_required`（5 号字段）
Implicit 与 Password 流程	仍是 `oneof` 的 3 号和 4 号成员，现标记为 `deprecated`
必填字段	v0.3.0 proto 中的安全相关消息都没有 `REQUIRED` 注解；v1.0.1 把上表中的必填字段标为必填
未变	五个 `SecurityScheme` 成员保持 1 至 5 号字段，`MutualTlsSecurityScheme` 在两个版本中都存在

官方迁移指南涵盖了 OAuth 流程的变化，但没有提到 security 的重命名。