feat!: Add mTLS to SecuritySchemes, add oauth2 metadata url field, allow Skills to specify Security (#901)

mikeas1 · holtskinner · web-flow · commit e162c0c6c4f6 · 2025-07-29T13:39:27.000-06:00
# Description

This PR makes changes to our security representations in AgentCards:

1. Adds a new MutualTLSSecurityScheme type for indicating mTLS
connection requirements. This matches the same field in the OpenAPI
specification v3.1. This type is pretty lacking: there is no way to
indicate any requirements on the certificate that is presented by the
client. I expect we'll want to extend this in the future (for example,
we may want to allow an agent to indicate that a SPIFFE certificate must
be presented). For now, users are advised to put requirements in the
description field.
2. Adds a field for specifying a URL for OAuth2 provider metadata. This
is planned for OpenAPI Specification v3.2, which has not yet been
released. This allows clients to fetch additional information about the
OAuth provider, such as to discover if they support Dynamic Client
Registration.
3. Allows AgentSkills to specify a `security` field. This allows agents
to indicate security requirements for leveraging a particular skill.

I also clarified the usage and expectations for the `security` field in
the base AgentCard.

This change is marked backwards incompatible due to the addition of the
MutualTLSSecurityScheme, which adds a new type to an exhaustive enum
(the security scheme `anyOf`).

Release-As: 0.3.0

---------

Co-authored-by: Holt Skinner &lt;13262395+holtskinner@users.noreply.github.com&gt;
Co-authored-by: Holt Skinner &lt;holtskinner@google.com&gt;
diff --git a/.github/actions/spelling/allow.txt b/.github/actions/spelling/allow.txt
@@ -214,6 +214,7 @@ notif
 npush
 objc
 octicons
+oidc
 ollama
 oneof
 oreilly
diff --git a/specification/grpc/a2a.proto b/specification/grpc/a2a.proto
@@ -372,6 +372,18 @@ message AgentCard {
   map<string, SecurityScheme> security_schemes = 8;
   // protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
   // Security requirements for contacting the agent.
+  // This list can be seen as an OR of ANDs. Each object in the list describes
+  // one possible set of security requirements that must be present on a
+  // request. This allows specifying, for example, "callers must either use
+  // OAuth OR an API Key AND mTLS."
+  // Example:
+  // security {
+  //   schemes { key: "oauth" value { list: ["read"] } }
+  // }
+  // security {
+  //   schemes { key: "api-key" }
+  //   schemes { key: "mtls" }
+  // }
   repeated Security security = 9;
   // protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
   // The set of interaction modes that the agent supports across all skills.
@@ -451,6 +463,12 @@ message AgentSkill {
   repeated string input_modes = 6;
   // Possible output modalities produced
   repeated string output_modes = 7;
+  // protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
+  // Security schemes necessary for the agent to leverage this skill.
+  // As in the overall AgentCard.security, this list represents a logical OR of
+  // security requirement objects. Each object is a set of security schemes
+  // that must be used together (a logical AND).
+  repeated Security security = 8;
 }
 
 // AgentCardSignature represents a JWS signature of an AgentCard.
@@ -487,6 +505,7 @@ message SecurityScheme {
     HTTPAuthSecurityScheme http_auth_security_scheme = 2;
     OAuth2SecurityScheme oauth2_security_scheme = 3;
     OpenIdConnectSecurityScheme open_id_connect_security_scheme = 4;
+    MutualTlsSecurityScheme mtls_security_scheme = 5;
   }
 }
 
@@ -518,6 +537,9 @@ message OAuth2SecurityScheme {
   string description = 1;
   // An object containing configuration information for the flow types supported
   OAuthFlows flows = 2;
+  // URL to the oauth2 authorization server metadata
+  // [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414). TLS is required.
+  string oauth2_metadata_url = 3;
 }
 
 message OpenIdConnectSecurityScheme {
@@ -528,6 +550,11 @@ message OpenIdConnectSecurityScheme {
   string open_id_connect_url = 2;
 }
 
+message MutualTlsSecurityScheme {
+  // Description of this security scheme.
+  string description = 1;
+}
+
 message OAuthFlows {
   oneof flow {
     AuthorizationCodeOAuthFlow authorization_code = 1;
diff --git a/specification/json/a2a.json b/specification/json/a2a.json
diff --git a/types/src/types.ts b/types/src/types.ts
@@ -66,7 +66,8 @@ export type SecurityScheme =
   | APIKeySecurityScheme
   | HTTPAuthSecurityScheme
   | OAuth2SecurityScheme
-  | OpenIdConnectSecurityScheme;
+  | OpenIdConnectSecurityScheme
+  | MutualTLSSecurityScheme;
 // --8<-- [end:SecurityScheme]
 
 // --8<-- [start:SecuritySchemeBase]
@@ -114,6 +115,16 @@ export interface HTTPAuthSecurityScheme extends SecuritySchemeBase {
 }
 // --8<-- [end:HTTPAuthSecurityScheme]
 
+// --8<-- [start:MutualTLSSecurityScheme]
+/**
+ * Defines a security scheme using mTLS authentication.
+ */
+export interface MutualTLSSecurityScheme extends SecuritySchemeBase {
+  /** The type of the security scheme. Must be 'mutualTLS'. */
+  readonly type: "mutualTLS";
+}
+// --8<-- [end:MutualTLSSecurityScheme]
+
 // --8<-- [start:OAuth2SecurityScheme]
 /**
  * Defines a security scheme using OAuth 2.0.
@@ -123,6 +134,11 @@ export interface OAuth2SecurityScheme extends SecuritySchemeBase {
   readonly type: "oauth2";
   /** An object containing configuration information for the supported OAuth 2.0 flows. */
   flows: OAuthFlows;
+  /**
+   * URL to the oauth2 authorization server metadata
+   * [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414). TLS is required.
+   */
+  oauth2MetadataUrl?: string;
 }
 // --8<-- [end:OAuth2SecurityScheme]
 
@@ -283,6 +299,15 @@ export interface AgentSkill {
    * The set of supported output MIME types for this skill, overriding the agent's defaults.
    */
   outputModes?: string[];
+  /**
+   * Security schemes necessary for the agent to leverage this skill.
+   * As in the overall AgentCard.security, this list represents a logical OR of security
+   * requirement objects. Each object is a set of security schemes that must be used together
+   * (a logical AND).
+   *
+   * @TJS-examples [[{"google": ["oidc"]}]]
+   */
+  security?: { [scheme: string]: string[] }[];
 }
 // --8<-- [end:AgentSkill]
 
@@ -415,6 +440,11 @@ export interface AgentCard {
   /**
    * A list of security requirement objects that apply to all agent interactions. Each object
    * lists security schemes that can be used. Follows the OpenAPI 3.0 Security Requirement Object.
+   * This list can be seen as an OR of ANDs. Each object in the list describes one possible
+   * set of security requirements that must be present on a request. This allows specifying,
+   * for example, "callers must either use OAuth OR an API Key AND mTLS."
+   *
+   * @TJS-examples [[{"oauth": ["read"]}, {"api-key": [], "mtls": []}]]
    */
   security?: { [scheme: string]: string[] }[];
   /**

-Original file line number
+Diff line change
 npush
 objc
 octicons
 +oidc
 ollama
 oneof
 oreilly