Skip to main content

Delegate agent identity with token exchange

When an AI agent acts on a user's behalf (reading their calendar, filing a ticket, calling a tool through a Virtual MCP Server (vMCP)), you usually want ToolHive to record both facts: who the human is, and which agent actually made the call, so audit logs and authorization policies can tell "Alice, directly" apart from "an agent, acting for Alice." RFC 8693 token-exchange delegation is how ToolHive does this: a pre-provisioned client exchanges a user's token for one that names both the user and the agent acting for them.

info

The fields covered here (trustedIssuers, inboundGrants.tokenExchange, spiffeTrustDomains, and inboundGrants.spiffeClientAuth) are also available on a plain MCPServer through MCPExternalAuthConfig's embeddedAuthServer block, using the same configuration structure shown below under authServerConfig. This page focuses on VirtualMCPServer because delegation is primarily useful when an agent orchestrates calls across multiple backends on a user's behalf. For the MCPServer field reference, see Set up the embedded authorization server in Kubernetes.

Overview​

If you're deciding which of ToolHive's ways to get a token fits your case, see the comparison in Choose a way to get a token.

This page covers how ToolHive mints a delegated token. If you're looking for how ToolHive reads an act claim on an incoming token, for example because your own IdP already performs RFC 8693 delegation upstream of ToolHive, see Delegated identities and the act claim.

RFC 8693 delegation with a pre-provisioned delegate client​

Delegation requires two pieces of configuration on authServerConfig: an inboundGrants.tokenExchange.delegateClients entry for the agent that will perform the exchange, and an inboundGrants.tokenExchange.issuerPolicies entry that tells ToolHive which external issuer's tokens it will accept as a subject token, and which actors are allowed to act on behalf of the tokens it issues.

For how to create the delegateClients entry itself (the client ID, secret, audiences, and scopes), see Pre-provision confidential clients for token exchange. delegateClients is separate from Dynamic Client Registration (plain, confidential, or private_key_jwt). A delegateClients entry has a clientId and secret you choose and create yourself, never one a client obtains by registering itself. A client uses one path or the other; issuerPolicies[].allowedDelegateClients (below) is what authorizes either kind of client_id to actually perform an exchange, once it has one.

Both entries are required. The issuer policy grants a delegate client permission to accept a subject token from the external issuer; on its own it doesn't create a usable exchange path, because RFC 8693 requires authenticated access to /oauth/token and the delegate client is what authenticates.

This section focuses on the issuer-policy side, which authorizes delegation:

VirtualMCPServer: delegation configuration
spec:
authServerConfig:
issuer: https://vmcp.example.com
# ...
trustedIssuers:
- name: entra-issuer
issuerUrl: 'https://sts.windows.net/<TENANT_ID>/'
jwksUrl: 'https://login.windows.net/<TENANT_ID>/discovery/v2.0/keys'
inboundGrants:
tokenExchange:
delegateClients:
- clientId: coding-agent
clientSecretRef:
name: coding-agent-secret
key: client-secret
scopes:
- openid
audiences:
- https://vmcp.example.com/mcp-resource
issuerPolicies:
- issuerRef: entra-issuer
expectedAudience: 'https://vmcp.example.com/mcp-resource'
# "appid" is where Microsoft Entra v1 tokens carry the calling
# application's client ID, verified against a real Entra tenant.
# Other issuers use a different claim name for the same purpose
# (for example Okta's client_credentials tokens use "cid"); check
# your issuer's own token claims, or use the literal value
# "client_id" (a sentinel, not a claim name) to read the token's
# client_id claim.
actorClaim: appid
allowedActors:
- <APP1_CLIENT_ID>
allowedDelegateClients:
- coding-agent

trustedIssuers[].name gives this issuer declaration a stable identifier that issuerPolicies[].issuerRef binds a grant policy to; issuerUrl and jwksUrl identify the external identity provider that minted the subject token the agent will present (in this example, a user's Entra sign-in as a separate application, App1). expectedAudience must match the audience already present on that subject token. actorClaim names the claim carrying the calling application's client ID; it defaults to azp when you leave it unset. allowedDelegateClients is what binds an external actor to a specific ToolHive delegate client. Without it, every confidential client holding the token-exchange grant would be equivalent for delegation purposes. Set it to ["*"] to declare that permissiveness explicitly; the wildcard must stand alone, and combining it with specific client IDs is rejected at admission. If you also enable allowMayAct, set it explicitly to false rather than omitting it, since an omitted allowMayAct combined with the wildcard is rejected by a validation rule that can't yet distinguish "not set" from "false" (tracked upstream).

For the complete field list, including jwksUrl, caBundleRef, allowPrivateIPs, and the per-issuer insecureAllowHTTP, see the MCPExternalAuthConfig schema reference.

Trust a private issuer CA​

When the external issuer uses a private CA for its discovery or JWKS endpoint, store its PEM certificate in a ConfigMap and reference it from the issuer:

VirtualMCPServer: trusted issuer private CA
spec:
authServerConfig:
trustedIssuers:
- issuerUrl: 'https://<ISSUER_HOST>'
caBundleRef:
configMapRef:
name: external-issuer-ca
key: ca.crt

ToolHive uses the additional certificate only for this issuer's discovery and JWKS requests. Restrict write access to this ConfigMap because it defines the trust anchor used to validate subject tokens.

Walk through an exchange​

Once configured, the agent (coding-agent) presents a user's subject token to ToolHive's /oauth/token endpoint using its own client credentials:

curl -s -X POST https://vmcp.example.com/oauth/token \
-u "coding-agent:<CLIENT_SECRET>" \
-d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
-d "subject_token=<SUBJECT_TOKEN>" \
-d "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
-d "audience=https://vmcp.example.com/mcp-resource"

SUBJECT_TOKEN is the user's own token from the external issuer. In this example, an Entra access token issued to App1 with aud set to the backend resource and appid set to App1's client ID. ToolHive validates that token against the matching trustedIssuers entry, confirms App1 is an allowed actor, and confirms coding-agent is an allowed delegate client, then issues a delegated access token. Decoding it shows the delegation:

{
"sub": "https://sts.windows.net/<TENANT_ID>/#<user-object-id>",
"act": {
"iss": "https://vmcp.example.com",
"sub": "coding-agent",
"act": {
"iss": "https://sts.windows.net/<TENANT_ID>/",
"sub": "<APP1_CLIENT_ID>"
}
}
}

sub identifies the user (qualified with the issuer to avoid collisions across identity providers). The outer act names the authenticated ToolHive client that performed the exchange, in act.sub, with act.iss set to the ToolHive issuer that minted the token. The nested act.act is the external actor asserted by the subject token itself, the application the user actually signed in through. This nested shape is how ToolHive represents a two-hop delegation chain: an external application acting for a user, and a ToolHive client acting on top of that.

inboundGrants.tokenExchange.issuerPolicies entries support three independent ways to authorize delegation from an external issuer. Any one of them being satisfied is sufficient; they aren't layered as an all-must-pass chain:

FieldHow it authorizes
allowedActorsA static allowlist of actorClaim values. Use this for a fixed, known set of external applications (like App1 above).
actorMatcherAn admin-authored CEL expression evaluated against the subject token's complete, signature-verified claims map (bound as claims). Use this when the authorization rule can't be expressed as a flat allowlist, for example matching on a claim pattern or a combination of claims. Must evaluate to a boolean; a non-boolean result denies the token at evaluation time.
allowMayActTrusts a may_act claim the external issuer itself already asserts on the subject token, bypassing allowedActors and actorMatcher entirely. Defaults to false; external issuers must be opted in explicitly, since may_act shifts the consent decision to the external IdP. Doesn't apply to self-issued subject tokens. Enabling it alongside allowedDelegateClients: ["*"] is rejected at admission.

allowedDelegateClients is a separate, always-required control: it restricts which ToolHive clients may perform the exchange, independent of which external actor the subject token names. allowedActors, actorMatcher, and allowMayAct all authorize the external actor; allowedDelegateClients authorizes the ToolHive-side client.

Secretless delegate clients with private_key_jwt​

A delegateClients entry requires ToolHive to hold a shared secret for the agent. Setting allowPrivateKeyJWTRegistration: true on authServerConfig instead lets an agent register itself via Dynamic Client Registration (DCR) using only a keypair it generates locally. ToolHive never issues, stores, or transmits a secret for that client.

VirtualMCPServer: allow private_key_jwt registration
spec:
authServerConfig:
issuer: https://vmcp.example.com
allowPrivateKeyJWTRegistration: true

Registration is unauthenticated, the same as ordinary DCR, so enabling this lets any caller who can reach /oauth/register register a private_key_jwt client.

If you're comparing ways to avoid provisioning a client secret at all, see also Client ID Metadata Document (CIMD), which lets a client authenticate from a hosted metadata document instead of either a shared secret or a keypair registered through DCR. CIMD doesn't involve delegation, so it's unrelated to the exchange described on this page.

Register and authenticate with a keypair​

The agent generates an RSA (or EC) keypair and declares only the public half at registration:

POST /oauth/register
curl -s -X POST https://vmcp.example.com/oauth/register \
-H "Content-Type: application/json" \
-d '{
"redirect_uris": ["http://localhost:19999/callback"],
"token_endpoint_auth_method": "private_key_jwt",
"token_endpoint_auth_signing_alg": "RS256",
"grant_types": ["urn:ietf:params:oauth:grant-type:token-exchange"],
"jwks": {"keys": [{"kty": "RSA", "use": "sig", "alg": "RS256", "kid": "agent-key", "n": "<MODULUS>", "e": "AQAB"}]}
}'

The response carries a client_id and no client_secret. The keypair itself is the credential. To authenticate at the token endpoint, the agent signs a client_assertion JWT with its private key (iss and sub set to its own client_id, aud set to the auth server's issuer, with a unique jti), then presents it alongside the subject token:

POST /oauth/token
curl -s -X POST https://vmcp.example.com/oauth/token \
-d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
-d "subject_token=<SUBJECT_TOKEN>" \
-d "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
-d "audience=https://vmcp.example.com/mcp-resource" \
-d "client_id=<DCR_CLIENT_ID>" \
-d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
-d "client_assertion=<SIGNED_ASSERTION>"

No client_secret parameter appears anywhere in this request. ToolHive validates the client_assertion's signature against the JWKS declared at registration and rejects a replayed client_assertion (the same jti presented twice) on the second attempt. ToolHive also accepts the token endpoint URL as the aud value, or an aud array that contains either value. These forms are deprecated, and a future release will require the issuer as the only audience.

ToolHive tolerates up to 60 seconds of clock skew between the agent and the server: it accepts an assertion until 60 seconds after its exp, and from 60 seconds before its iat or nbf. The exp claim can be at most 6 minutes ahead of the server clock, and it can't be earlier than iat. You can't configure the skew margin.

ToolHive returns HTTP 401 invalid_client for every rejected assertion: a bad signature, an unknown kid, a wrong aud, a reused jti, an exp outside the skew margin, an nbf or iat too far in the future, or an exp more than 6 minutes ahead. A request that sets client_assertion_type but omits client_assertion gets HTTP 400 invalid_request.

Everything else about the exchange, subject-token validation against trustedIssuers, actor resolution, and the resulting act claim, works exactly as in the pre-provisioned case above; the issued token's act.sub is the DCR-assigned client_id instead of a statically configured one.

ToolHive rejects registrations whose keys fall outside these limits:

  • RSA keys must have a modulus between 2048 and 8192 bits and an odd public exponent between 3 and 65537.
  • The inline jwks can contain at most 10 keys.

ToolHive also checks stored clients against these limits, so a client whose registered key falls outside them fails authentication with invalid_client and must register again.

Authenticate workloads with SPIFFE SVIDs​

If your agents run as SPIFFE workloads (for example, attested by SPIRE), they already hold a short-lived SPIFFE Verifiable Identity Document (SVID) issued by your SPIFFE infrastructure. Instead of provisioning a secret or a keypair for each agent, you can map SPIFFE IDs to OAuth clients and let each workload authenticate to ToolHive's token endpoint with its SVID. ToolHive supports both SVID formats:

  • JWT-SVID: the workload sends the SVID as a client_assertion. This works on any port, including behind an ingress that terminates TLS.
  • X.509-SVID: the workload presents the SVID as a TLS client certificate (mutual TLS). This requires the authorization server's own TLS listener and a TLS connection that reaches it end to end.

A SPIFFE client can use only the RFC 8693 token-exchange grant and has no client secret. To have a workload get a token in its own name, with no user subject token, use the JWT-bearer grant instead.

Declare the trust domain and client associations​

Two blocks under authServerConfig work together. spiffeTrustDomains declares each trust domain you accept and where ToolHive loads its trust bundle from. inboundGrants.spiffeClientAuth maps a SPIFFE ID, or a pattern of SPIFFE IDs, to one OAuth client ID with its allowed audiences and scopes.

First, store your trust domain's bundle in a ConfigMap. The bundle must be a SPIFFE trust bundle in JWKS format, such as the output of spire-server bundle show -format spiffe:

kubectl create configmap spiffe-trust-bundle \
--namespace toolhive-system \
--from-file=bundle.json=./bundle.json

Then reference it from the VirtualMCPServer:

VirtualMCPServer: SPIFFE client authentication
spec:
authServerConfig:
# X.509-SVID clients reach the TLS listener, so the issuer uses port 8443
issuer: https://vmcp.example.com:8443
# Required only for X.509-SVID authentication (spiffe_x509)
tlsListener:
certificateSecretRef:
name: auth-server-tls
key: tls.crt
privateKeySecretRef:
name: auth-server-tls
key: tls.key
spiffeTrustDomains:
- name: production
trustDomain: example.org
methods: [spiffe_x509, spiffe_jwt]
bundleSource:
type: file
file:
configMapName: spiffe-trust-bundle
configMapKey: bundle.json
inboundGrants:
spiffeClientAuth:
- trustDomainRef: production
principalPattern: spiffe://example.org/ns/agents/sa/reporting-agent
clientId: reporting-agent
methods: [spiffe_jwt, spiffe_x509]
audiences: [https://vmcp.example.com/mcp-resource]
scopes: [openid]

spiffeTrustDomains fields:

FieldDescription
nameRequired. A local name that spiffeClientAuth[].trustDomainRef refers to. Every declared trust domain must be referenced.
trustDomainRequired. The SPIFFE trust domain, such as example.org.
methodsRequired. The authentication methods this domain allows: spiffe_jwt, spiffe_x509, or both.
bundleSource.typeRequired. Set to file. The schema also accepts bundle_endpoint and workload_api, but ToolHive rejects them during reconciliation.
bundleSource.file.*Required for file. configMapName and configMapKey name the ConfigMap key that holds the trust bundle.

spiffeClientAuth fields:

FieldDescription
trustDomainRefRequired. The name of a spiffeTrustDomains entry.
principalPatternRequired. An exact SPIFFE ID, or one ending in /* to match every ID below that path. It must start with spiffe://<trustDomain>/. Patterns must not overlap.
clientIdRequired. The OAuth client ID that matching workloads authenticate as. It must be unique and must not match a delegateClients[].clientId.
methodsRequired. spiffe_jwt, spiffe_x509, or both. Must be a subset of the trust domain's methods. spiffe_x509 requires tlsListener and an https:// issuer.
audiencesRequired. The RFC 8693 audiences this client may request.
scopesRequired. The scopes this client may request.
resourcesOptional. RFC 8707 resource indicators this client may request. Each must be one of the server's allowed audiences.

ToolHive polls the bundle file every 30 seconds, so a rotated bundle in the ConfigMap takes effect without a restart. If ToolHive can't load a fresh bundle for 24 hours, it treats the last good bundle as stale and SPIFFE client authentication fails until a fresh bundle loads.

You can omit upstreamProviders when you configure spiffeClientAuth. The authorization server then runs in token-only mode, and the VirtualMCPServer can't also set incomingAuth.authzConfig.

Exchange a token with a JWT-SVID​

The workload fetches a JWT-SVID whose only audience is the exact issuer value of the authorization server, then sends it as the client_assertion with the SPIFFE assertion type:

POST /oauth/token
curl -s -X POST https://vmcp.example.com:8443/oauth/token \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
--data-urlencode "subject_token=<SUBJECT_TOKEN>" \
--data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
--data-urlencode "audience=https://vmcp.example.com/mcp-resource" \
--data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-spiffe" \
--data-urlencode "client_assertion=<JWT_SVID>"

client_id is optional here. When you omit it, ToolHive picks the client from the SPIFFE ID in the verified SVID; when you include it, it must match that association's clientId. The SVID must expire within 6 minutes and be at most 16 KiB. ToolHive doesn't track JWT-SVID jti values, so keep SVID lifetimes short.

Exchange a token with an X.509-SVID​

With spiffe_x509 enabled, the authorization server's TLS listener on port 8443 asks connecting clients for a certificate. The workload connects to port 8443 with its X.509-SVID as the client certificate and names its client explicitly:

POST /oauth/token over mutual TLS
curl -s -X POST https://vmcp.example.com:8443/oauth/token \
--cert svid.pem --key svid_key.pem \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
--data-urlencode "subject_token=<SUBJECT_TOKEN>" \
--data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
--data-urlencode "audience=https://vmcp.example.com/mcp-resource" \
--data-urlencode "client_id=reporting-agent"

client_id is required for X.509, and the request must carry no other credential: no HTTP Basic header, client_secret, or client_assertion. ToolHive verifies the certificate chain against the trust bundle on every request and rejects chains longer than four certificates.

Because X.509 clients reach the authorization server through the TLS listener, set the issuer to port 8443 on a host that the listener certificate covers. Otherwise, ToolHive logs a warning at startup.

ToolHive reads the client certificate only from the TLS connection itself, never from a forwarded header such as X-Forwarded-Client-Cert. Use TLS passthrough to port 8443. A proxy or gateway that opens its own TLS connection to port 8443 authenticates as itself, so write principal patterns that can't match a proxy's or gateway's SPIFFE ID. Behind an ingress that terminates TLS, use JWT-SVIDs instead.

Subject tokens for SPIFFE clients​

A SPIFFE client isn't a delegate client, so it gets none of a delegate client's exemptions for ToolHive-issued tokens. The subject token can be either of these:

  • A token issued by this ToolHive authorization server. ToolHive accepts it when the token's client_id is the SPIFFE client's clientId, or when its may_act.sub names that clientId.
  • A token from an external issuer listed under trustedIssuers. The matching inboundGrants.tokenExchange.issuerPolicies entry must authorize the token's actor through allowedActors or actorMatcher, or through a may_act claim naming the SPIFFE client's clientId when allowMayAct is enabled. Its allowedDelegateClients must also list that clientId. See RFC 8693 delegation with a pre-provisioned delegate client for how to set up an issuer policy.

In both cases, the token's aud must include every audience the issued token gets. The issued token records the SPIFFE client in act.sub, using the configured clientId; the SPIFFE ID itself doesn't appear in the token.

warning

An allowedDelegateClients value of ["*"] matches every client, including every SPIFFE client. If you set it on an issuer policy, any SPIFFE client can exchange that issuer's tokens whose actor passes allowedActors or actorMatcher. List specific client IDs to keep SPIFFE clients out.

Next steps​

Troubleshooting​

ErrorLikely cause
invalid_client (exact hint varies by cause: wrong secret, wrong token_endpoint_auth_method, or a public client attempting a confidential-only grant)The delegate client must be confidential. Verify inboundGrants.tokenExchange.delegateClients[].clientSecretRef is set and the client authenticated with the matching secret and method.
HTTP 401 invalid_client for a private_key_jwt clientThe client_assertion failed validation. Check that it's signed with a key whose kid is in the registered JWKS, that aud is the issuer, that exp, nbf, and iat are within the 60-second skew margin of the server clock, that exp is at most 6 minutes ahead, and that each request uses a fresh jti.
invalid_grant: "The subject token does not authorize this client to act on behalf of the subject."The subject token's may_act.sub doesn't match the actor ToolHive resolved for this request.
invalid_grant: "This client is not authorized to exchange subject tokens from the external actor's issuer."The authenticated client isn't in issuerPolicies[].allowedDelegateClients for the issuer that minted the subject token.
invalid_grant: "The subject token was issued to a different client."The subject token's own client_id claim doesn't match the authenticated delegate client, and the client isn't in allowedDelegateClients.
invalid_request: "The subject token is invalid or could not be verified."The subject token failed signature, issuer, or audience validation against every configured trustedIssuers entry.
invalid_target: "The client is not permitted to request audience ..."The audience parameter on the exchange request isn't in the delegate client's audiences list. Request one of the listed audiences, or add the audience to delegateClients[].audiences.
HTTP 401 invalid_client for a SPIFFE client using an X.509-SVIDThe client certificate didn't reach the authorization server's TLS listener on port 8443, for example because an ingress terminated TLS, or the certificate doesn't match the association's principalPattern. Use TLS passthrough to port 8443, or switch the client to a JWT-SVID.
HTTP 401 invalid_client for a SPIFFE client using a JWT-SVIDCheck that the SVID's only audience is exactly the issuer, that it expires within 6 minutes, that its SPIFFE ID matches a principalPattern enabled for spiffe_jwt, and that the trust bundle in the ConfigMap is current.
Status condition: bundleSource: type "bundle_endpoint" is not supported by this build; only "file" is supportedSet bundleSource.type: file and supply the trust bundle through a ConfigMap. The same applies to workload_api.
CRD rejected: issuerPolicies[]: allowedDelegateClients: Required valueAn inboundGrants.tokenExchange.issuerPolicies entry is missing allowedDelegateClients. Add it.
CRD rejected: "delegateClients with an HTTP issuer require insecureAllowConfidentialOverLoopbackHTTP to be explicitly enabled"A delegate client uses a plain-HTTP issuer. Use an https:// issuer, or for local development set insecureAllowConfidentialOverLoopbackHTTP: true with a loopback issuer.