orcaqubits/a2a-authentication

A2A Authentication

Before writing code

Fetch live docs:

1. Fetch https://a2a-protocol.org/latest/specification/ for the authentication and security section
2. Web-search site:github.com a2aproject A2A authentication security schemes for auth scheme details
3. Web-search site:github.com a2aproject a2a-samples authentication for auth implementation examples
4. Fetch SDK docs for authentication middleware and client credential handling

Conceptual Architecture

Why Authentication Matters

In multi-agent systems, agents must verify each other's identity and authorize access:

• Server agents need to know who's calling them and whether they're authorized
• Client agents need to present valid credentials to access server agents
• Agent Cards declare what authentication is required upfront

Five Security Schemes

A2A supports the same security scheme types as OpenAPI 3.0:

1. API Key (apiKey)

A static key sent in a header or query parameter.

• Best for: Internal agents, simple integrations, development
• Agent Card declares: Header name and location
• Client provides: The key value in the specified header

2. HTTP Bearer (http with scheme: bearer)

A bearer token (JWT or opaque) in the Authorization header.

• Best for: Token-based auth, service-to-service with JWTs
• Agent Card declares: Bearer scheme, optional format hint
• Client provides: Authorization: Bearer <token>

3. OAuth 2.0 (oauth2)

Standard OAuth 2.0 flows for token acquisition.

• Best for: Production systems, fine-grained scopes, delegated access
• Agent Card declares: OAuth flows (clientCredentials, authorizationCode), token URL, scopes
• Client provides: Access token obtained from the OAuth server

Common flow for agent-to-agent: Client Credentials (machine-to-machine, no user involvement).

4. OpenID Connect (openIdConnect)

OIDC discovery-based authentication.

• Best for: Enterprise systems with identity providers, SSO environments
• Agent Card declares: OIDC discovery URL (openIdConnectUrl)
• Client provides: Token obtained via OIDC flow

5. Mutual TLS (mutualTLS)

Client certificate-based authentication.

• Best for: High-security environments, zero-trust networks
• Agent Card declares: mTLS requirement
• Client provides: Client certificate during TLS handshake

Agent Card Authentication Declaration

Authentication requirements are declared in the Agent Card using two top-level fields, securitySchemes (a map of named scheme definitions) and security (an array of required scheme references):

{
  "securitySchemes": {
    "oauth2_auth": {
      "type": "oauth2",
      "flows": {
        "clientCredentials": {
          "tokenUrl": "https://auth.example.com/token",
          "scopes": {
            "agent:read": "Read access",
            "agent:write": "Write access"
          }
        }
      }
    }
  },
  "security": [
    { "oauth2_auth": [] }
  ]
}

Extended Agent Card

The agent/authenticatedExtendedCard method allows agents to return a richer Agent Card to authenticated clients — exposing additional skills or capabilities that aren't visible to unauthenticated discovery.

Auth-Required State

If a task requires authentication mid-flow:

1. Server transitions task to auth-required state
2. Status message includes auth instructions
3. Client authenticates and resumes the task
4. Server transitions back to working

Best Practices

• Always use HTTPS for A2A communication in production
• Prefer OAuth 2.0 client credentials for production agent-to-agent auth
• Use API keys only for development or internal low-risk scenarios
• Rotate credentials regularly and support credential refresh
• Declare authentication in the Agent Card so clients know requirements before calling
• Implement rate limiting alongside authentication
• Log authentication failures for security monitoring
• Use the auth-required task state for dynamic auth challenges

Fetch the specification for exact authentication schema structures, security scheme field names, and the extended card method before implementing.