Agent2Agent Protocol, IBM Vault, & OAuth 2.0 On-Behalf-Of

I wrote a blog on using AI agent authorization with Agent2Agent protocol and IBM Vault that focused on setting up Vault as an OIDC provider to authenticate and authorize requests from an Agent2Agent client to a server. While it works, the post missed something rather critical: identity delegation. Basically, if I am an end user, I want to delegate my Agent2Agent (A2A) client to act on my behalf to access the A2A server.

It turns out a number of folks in the agent identity space Microsoft Entra Agent ID, Christian Posta) have been exploring and implementing RFC 8693: OAuth 2.0 Token Exchange as a way of facilitating and tracking identity delegation. At the time of this post, Vault did not have a secrets engine that that implemented this specification - so I did it as a proof of concept for my own education and knowledge. I ended up creating a Security Token Service (STS) with a custom Vault secrets engine that implements RFC 8693.

Step 1: get a subject token from Vault as OIDC provider

The general workflow for delegating identity required me to read the specification a few times. First, the end user authenticates to the client agent using an OIDC provider to get a subject token.

I set up Vault as an OIDC provider to support a may-act OIDC scope. This scope attaches a may_act claim to the id_token with a list of client agents allowed to act on the user's behalf.

locals {
  may_act_scope_name = "may-act"
  may_act_claim      = jsonencode([for agent, info in var.client_agents : { client_id = agent, sub = vault_identity_entity.client_agents[agent].id }])
}

resource "vault_identity_oidc_scope" "may_act" {
  name        = local.may_act_scope_name
  template    = <<EOT
{
  "client_id": "${vault_identity_oidc_client.agent.client_id}",
  "may_act": ${local.may_act_claim}
}
EOT
  description = "May act claim that includes what agents can act on behalf of user"
}

The client_id and the sub in the may_act claim refer to the client agent that requests delegated access, not the end user. The combination of client_id and sub enables the custom Vault secrets engine to check that the client agent's Vault role (client_id) and entity ID (sub) can have access on behalf of the end user. I decided both needed to be checked because Vault assigns a new entity for every role for each authentication method.

With the correct OIDC scope for the OIDC request, Vault returns a subject access token with a set of claims allowing certain entities to act on behalf of the user.

{
  "at_hash": "gBJNAqZ6z7Yz7UG-z69Leg",
  "aud": "Sy0uWliApQrPApxpLp7gYVD0wAjvQNse",
  "c_hash": "PLTNZjVHMxhDWOLIeZ_sQA",
  "client_id": "Sy0uWliApQrPApxpLp7gYVD0wAjvQNse",
  "exp": 1776796482,
  "iat": 1776792882,
  "iss": "$VAULT_ADDR/v1/identity/oidc/provider/agent",
  "may_act": [
    {
      "client_id": "test-client",
      "sub": "83b1d088-c7d5-b8a4-dd7b-99baca521f8d"
    }
  ],
  "namespace": "root",
  "sub": "50099deb-d0cf-911b-4310-64a173c542a6"
}

Note that if you have multiple entities that can act on behalf of a user, you'd need to create different scopes for each. As long as the OIDC provider supports the various scopes with different may_act claims, your end user can adjust which entities may act on their behalf.

Beyond defining the scope, I set a few other configurations for Vault as a OIDC provider. The full code example is located on GitHub. You can use another identity provider as an OIDC provider as well, as long as they provide a subject token with the may_act claim.

Step 2: get an actor token from Vault's identity secrets engine

Next, the client agents needs to request an actor token with a client_id and sub identifying the agent. I set up the Vault identity secrets engine to generate a JWT with the required claims.

{
  "aud": "test-client",
  "client_id": "test-client",
  "exp": 1776881849,
  "iat": 1776795449,
  "iss": "$VAULT_ADDR/v1/identity/oidc",
  "namespace": "root",
  "scope": "helloworld:read",
  "sub": "83b1d088-c7d5-b8a4-dd7b-99baca521f8d"
}

The identity secrets engine requires the token request to be tied to an entity, which makes it ideal for generating the actor token. The entity ID indicates the authentication and role making the request. For example, the sub claim includes an entity ID tied to a few authentication methods and roles, including the Kubernetes and AppRole auth methods.

$ vault read identity/entity/id/83b1d088-c7d5-b8a4-dd7b-99baca521f8d

Key                    Value
---                    -----
aliases                [map[canonical_id:83b1d088-c7d5-b8a4-dd7b-99baca521f8d creation_time:2026-04-20T16:50:33.077473683Z custom_metadata:<nil> id:87db0c7d-032b-ad5c-c3fb-d9faee1686f7 last_update_time:2026-04-20T17:54:26.863503728Z local:false merged_from_canonical_ids:<nil> metadata:map[service_account_name:test-client service_account_namespace:default service_account_secret_name: service_account_uid:2505bc80-5765-4f18-9f60-b4877d860350] mount_accessor:auth_kubernetes_6cb5b3d7 mount_path:auth/kubernetes/ mount_type:kubernetes name:2505bc80-5765-4f18-9f60-b4877d860350] map[canonical_id:83b1d088-c7d5-b8a4-dd7b-99baca521f8d creation_time:2026-04-21T14:21:23.194441388Z custom_metadata:map[] id:8a3cd010-1a3e-1918-1459-f873767c8a46 last_update_time:2026-04-21T14:21:23.194441388Z local:false merged_from_canonical_ids:<nil> metadata:<nil> mount_accessor:auth_approle_7135b542 mount_path:auth/approle/ mount_type:approle name:test-client]]
name                   test-client

After some research and testing, it seems that the scope claim does not matter so much for the actor token. For the full configuration to set up the identity secrets engine, review the example code.

Step 3: request a delegated access token from Vault

At this point, I realized I needed to create a custom secrets engine in Vault to support token exchange. I won't go into the specifics of developing the secrets engine, since most of it involved reading the spec and making sure it conformed to the right claims. The code for the plugin is on GitHub.

This plugin is not officially supported - its main intention is a proof-of-concept. As a result, use it with caution. Some important points:

The subject token's signature gets verified against a subject token's JWKS endpoint (OIDC provider).
The actor token's signature gets verified against the actor token's JWKS endpoint (identity secrets engine).
When requesting the delegated access token from Vault includes parameters for scope and aud.

This ensures the authenticity and integrity of the claims while keeping the implementation Vault-agnostic. While I could introspect the actor token directly against the identity secrets engine, I decided that a public JWKS endpoint was a better approach so I didn't have to pass a Vault token to the secrets engine.

After validating and verifying the subject and actor tokens, the custom secrets engine generates an access token with an act claim. The act claim identifies the actor who requested access on behalf of the end user. The custom secrets engine appends scope to audit the scope requested by each actor.

{
  "act": {
    "client_id": "test-client",
    "scope": "helloworld:read",
    "sub": "83b1d088-c7d5-b8a4-dd7b-99baca521f8d"
  },
  "aud": "helloworld-server",
  "client_id": "test-client",
  "exp": 1776796510,
  "iat": 1776792910,
  "iss": "$VAULT_ADDR/v1/sts",
  "scope": "helloworld:read",
  "sub": "50099deb-d0cf-911b-4310-64a173c542a6"
}

If you have another client agent who requests on behalf of a client agent, the secrets engine generates an access token with a nested act claim to denote the delegation chain. Use the access token for the original client agent as the subject token for the second exchange. You need an actor token for the second agent, as the second agent is acting on behalf of the first client acting on behalf of the end user (confusing, I know). Based on RFC 8693, the custom secrets engine will only evaluate the top-level actor against the may_act claim. Nested actor claims are for audit purposes.

The custom secrets engine has to be registered with the Vault server. I won't dive too deeply into the registration workflow in this post. If you want to learn more, check out the Terraform configuration that downloads the plugin binaries to a PersistentVolume on Kubernetes and the script to register the binaries.

Step 4: Update A2A agents

The access token is what the client agent passes to the server agent. The server agent verifies the access token's signature against the custom secrets engine's JWKS endpoint, checks the aud claim matches the name of the server agent, and verifies the issuer comes from the custom secrets engine.

If the access token does not contain the correct aud or the correct scope claim, the server agent does not allow the client agent to access its skills. The server agent does not have any direct dependencies on Vault. It uses the custom secrets engine's OpenID Connect configuration endpoint to get the JWKS endpoint for token verification.

The client agent does need access to Vault in order to get the subject and actor token. Rather than have the client agent access the Vault API, I used Vault Agent to read the required credentials to generate subject and actor tokens from Vault and write them to files for the client agent to use.

## omitted for clarity

    template {
      metadata {
        labels = {
          app = local.test_client_name
        }
        annotations = {
          "vault.hashicorp.com/agent-inject"                              = "true"
          "vault.hashicorp.com/role"                                      = "test-client"
          "vault.hashicorp.com/agent-inject-token"                        = "true"
          "vault.hashicorp.com/agent-run-as-same-user"                    = "true"
          "vault.hashicorp.com/tls-skip-verify"                           = "true"
          "vault.hashicorp.com/agent-inject-secret-client_secrets.json"   = "identity/oidc/client/agent"
          "vault.hashicorp.com/agent-inject-template-client_secrets.json" = <<-EOT
            {
            {{- with secret "identity/oidc/client/agent" }}
                "client_id": "{{ .Data.client_id }}",
                "client_secret": "{{ .Data.client_secret }}",
                "redirect_uris": {{ .Data.redirect_uris | toJSON }}
            {{- end }}
            }
          EOT
          "vault.hashicorp.com/agent-inject-secret-oidc_provider.json"    = "identity/oidc/provider/agent/.well-known/openid-configuration"
          "vault.hashicorp.com/agent-inject-template-oidc_provider.json"  = <<-EOT
            {
            {{- with secret "identity/oidc/provider/agent/.well-known/openid-configuration" }}
                "authorization_endpoint": "{{ .Data.authorization_endpoint }}",
                "issuer": "{{ .Data.issuer }}",
                "token_endpoint": "{{ .Data.token_endpoint }}",
                "userinfo_endpoint": "{{ .Data.userinfo_endpoint }}"
            {{- end }}
            }
          EOT
          "vault.hashicorp.com/agent-inject-secret-actor_token"           = "identity/oidc/token/test-client"
          "vault.hashicorp.com/agent-inject-template-actor_token"         = <<-EOT
            {{- with secret "identity/oidc/token/test-client" -}}
            {{ .Data.token }}
            {{- end }}
          EOT
        }
      }

Note that test-client runs with a Kubernetes service account. I configured a Vault role for the Kubernetes auth method and an alias for the test-client entity tied to the test-client service account. This ensures that when the test-client requests an actor token, it has an entity ID.

resource "vault_identity_entity_alias" "client_agents" {
  for_each       = var.client_agents
  name           = kubernetes_service_account_v1.client_agents[each.key].metadata[0].uid
  mount_accessor = vault_auth_backend.kubernetes.accessor
  canonical_id   = vault_identity_entity.client_agents[each.key].id
}

resource "vault_kubernetes_auth_backend_role" "client_agents" {
  for_each                         = var.client_agents
  backend                          = vault_auth_backend.kubernetes.path
  role_name                        = each.key
  bound_service_account_names      = [each.key]
  bound_service_account_namespaces = [each.value.k8s_namespace]
  token_ttl                        = 3600
  token_policies                   = [vault_policy.actor_token[each.key].name, vault_policy.agent_oidc_client.name, vault_policy.oauth_exchange_token[each.key].name]
}

While you can write code in your A2A client agent to authenticate to Vault and get the credentials, I found it easier to use Vault Agent to write them to a file for the client agent to consume. When the credentials expire, Vault Agent will write new credentials to the file.

End-to-end workflow

To demonstrate the workflow, the test-client includes a UI that has the end user log in and obtain the subject token from Vault as an OIDC provider.

Then, the end user requests a delegated access token with a specific scope and subject to access the A2A server agent. The test-client receives an access token from Vault's custom secrets engine.

The test-client agent uses the access token to successfully request a message from helloworld-server.

There are two ways in which the client agent does not have sufficient permissions to act on behalf of the end user to call the server agent.

First, if the client agent's actor token identity does not match the end user's subject token may_act claim, the Vault custom secrets engine does not issue a delegated access token.

Second, if the test-client uses an access token with insufficient scopes or incorrect server agent as the subject, the server agent denies access.

As a check, I reviewed the Vault audit logs to verify if it logged the end user requests to the OIDC provider, actor token requests from the client agent, and the delegated access token request from the client agent. The good news - it does! However, you have to tune the secrets engine to output the claims as non-HMAC keys. For example, I used the vault secrets tune subcommand to make it more clear for me to read.

vault secrets tune -audit-non-hmac-request-keys=scope -audit-non-hmac-request-keys=subject -audit-non-hmac-request-keys=audience sts

By configuring Vault as an OIDC provider, the identity secrets engine for the actor token, and a custom token exchange secrets engine for delegation, you can track and enforce some agent-to-agent communication.

Summary

Overall, this turned out to be far more challenging to implement than expected. It took quite a bit of reverse engineering the specification, reviewing the idea with other folks, arguing with my coding agent, and deploying Vault repeatedly.

The custom secrets engine I created for token exchange has a workflow that should go in the identity secrets engine as it has the same general structure. For my purposes, I ended up developing it as a separate secrets engine to I don't have to maintain a fork of the identity secrets engine plugin. I learned quite a bit about entity IDs and OAuth 2.0 in the process.

I do see a few problems with the approach. An administrator has to configure may_act claims for Vault entities and clients and assign (effectively) a role to every client agent. While this is something you can automate, I imagine it can get fairly complicated and challenging to maintain. It's also deterministic, which doesn't quite address the fact that agents are autonomous and might choose to act on other's behalf. As I am not comfortable letting an agent run amok with minimal supervision, I am fine with the administrative overhead.

Another problem is actually where to enforce the scope of what the client agent can do with the server agent. This is probably where an AI gateway would help, especially as it can review the access tokens and identify what a client agent can do with an MCP server or server agent. At the very least, this workflow does enable some kind of authentication request tracking so you can audit if and when a client agent requested access to a server agent or MCP server. I'll try working on this another day, probably with ContextForge.

In the meantime, if you're interested in how this works, check out the demo repository, which deploys a Kubernetes cluster and all of the components and configuration for Vault.

推荐订阅源

DEV Community