Document RFC 8693 token delegation and RFC 7523 JWT-bearer grant for the embedded auth server

What needs documentation?

ToolHive's embedded authorization server now supports two related agent-identity flows that aren't documented yet:

1. 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.
2. 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

• ToolHive architecture doc: docs/arch/17-token-exchange-delegation.md in stacklok/toolhive (merged to main)
• Config surface: MCPExternalAuthConfig/VirtualMCPServer.spec.authServerConfig.trustedIssuers[].allowedActors/actorMatcher/allowMayAct/jwtBearerGrant, delegateClients[], AllowClientAssertionAuth
• Tracked under stacklok/toolhive#5194 (embedded auth server RFC 8693 delegation epic) and its merged sub-issues

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.

Start with docs/arch/17-token-exchange-delegation.md, then read the existing embedded auth server sections in docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx and docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx. Add one guide covering both grant flows with end-to-end examples, and update reference/crds/mcpexternalauthconfig.mdx for the named fields; done means operators can configure and distinguish both flows without consulting source or schema.