What needs documentation?
ToolHive's embedded authorization server now supports two related agent-identity flows that aren't documented yet:
- RFC 8693 token-exchange delegation — a pre-registered delegate client exchanges a user's subject token for a delegated token carrying both the user's identity (
sub) and the agent's identity (act.sub), optionally with a further nested "actor" identity via CEL-based actorMatcher/allowedActors/allowMayAct policy on trustedIssuers. This also includes AllowClientAssertionAuth, which lets a delegate client authenticate with a self-issued client assertion instead of a static secret.
- RFC 7523 JWT-bearer assertion grant — a clientless grant where a third-party-issued JWT (an Entra client-credentials token, a SPIRE JWT-SVID, etc.) is presented directly to
/oauth/token with no client authentication, validated against a trustedIssuers[].jwtBearerGrant policy (subject bindings, accepted audiences, max assertion age), and exchanged for a ToolHive-native token.
Today's docs cover only the "confidential DCR" and plain client-pre-provisioning pieces of the embedded auth server (see docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx and docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx, section "Pre-provision confidential clients for token exchange"), and the concepts page's "Delegated identities and the act claim" section only describes reading an already-minted act claim on incoming tokens — not ToolHive minting one. The delegateClients[], actorMatcher, allowedActors, allowMayAct, and jwtBearerGrant config surfaces have no dedicated coverage anywhere in this repo.
Desired end state: a single new guide page covering both flows, where a reader configuring MCPExternalAuthConfig or VirtualMCPServer.spec.authServerConfig.trustedIssuers can find:
- what each flow is for and when to reach for it instead of confidential DCR or the existing "same-IdP token exchange" backend-auth pattern,
- the relevant config fields and how they compose with existing
delegateClients entries,
- at least one worked, end-to-end example per grant type (a delegate-client RFC 8693 exchange with
act, and a clientless RFC 7523 assertion grant from a workload identity source),
- how the two flows relate to each other and to the already-documented confidential DCR and plain backend token-exchange material.
CRD field reference coverage (e.g. a reference/crds/mcpexternalauthconfig.mdx update for actorMatcher/allowedActors/allowMayAct/jwtBearerGrant) is expected as part of this work, not a separate follow-up.
Context and references
Use case
As a platform operator wiring an AI agent (or a workload-identity system like SPIRE) into ToolHive, I want to configure delegated or clientless authentication into the embedded auth server and see a working example, instead of reverse-engineering it from the CRD schema or source.
What needs documentation?
ToolHive's embedded authorization server now supports two related agent-identity flows that aren't documented yet:
sub) and the agent's identity (act.sub), optionally with a further nested "actor" identity via CEL-basedactorMatcher/allowedActors/allowMayActpolicy ontrustedIssuers. This also includesAllowClientAssertionAuth, which lets a delegate client authenticate with a self-issued client assertion instead of a static secret./oauth/tokenwith no client authentication, validated against atrustedIssuers[].jwtBearerGrantpolicy (subject bindings, accepted audiences, max assertion age), and exchanged for a ToolHive-native token.Today's docs cover only the "confidential DCR" and plain client-pre-provisioning pieces of the embedded auth server (see
docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdxanddocs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx, section "Pre-provision confidential clients for token exchange"), and the concepts page's "Delegated identities and theactclaim" section only describes reading an already-mintedactclaim on incoming tokens — not ToolHive minting one. ThedelegateClients[],actorMatcher,allowedActors,allowMayAct, andjwtBearerGrantconfig surfaces have no dedicated coverage anywhere in this repo.Desired end state: a single new guide page covering both flows, where a reader configuring
MCPExternalAuthConfigorVirtualMCPServer.spec.authServerConfig.trustedIssuerscan find:delegateClientsentries,act, and a clientless RFC 7523 assertion grant from a workload identity source),CRD field reference coverage (e.g. a
reference/crds/mcpexternalauthconfig.mdxupdate foractorMatcher/allowedActors/allowMayAct/jwtBearerGrant) is expected as part of this work, not a separate follow-up.Context and references
docs/arch/17-token-exchange-delegation.mdin stacklok/toolhive (merged to main)MCPExternalAuthConfig/VirtualMCPServer.spec.authServerConfig.trustedIssuers[].allowedActors/actorMatcher/allowMayAct/jwtBearerGrant,delegateClients[],AllowClientAssertionAuthUse case
As a platform operator wiring an AI agent (or a workload-identity system like SPIRE) into ToolHive, I want to configure delegated or clientless authentication into the embedded auth server and see a working example, instead of reverse-engineering it from the CRD schema or source.