Add agent JWT auth and delegation guides - #1116
Draft
jhrozek wants to merge 2 commits into
Draft
Conversation
Add two vMCP guides covering the embedded auth server's agent-identity flows: RFC 8693 token-exchange delegation with a pre-provisioned delegate client, and the RFC 7523 JWT-bearer grant for clientless workload assertions. Link both from the concepts page and the vMCP and Kubernetes embedded auth server guides. Field names, CEL admission rules, error strings, and the delegated token's claim shape were verified against the ToolHive source. Refs #1109 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds new Virtual MCP Server (vMCP) documentation covering embedded auth server agent-identity flows (RFC 8693 delegation and RFC 7523 JWT-bearer), and wires the new guides into navigation and related conceptual context.
Changes:
- Adds two new vMCP guides: RFC 8693 delegation via delegate clients, and RFC 7523 JWT-bearer workload assertions.
- Updates the embedded auth server concept page with a new “minting delegated tokens” section and links into the new delegation guide.
- Updates vMCP and Kubernetes embedded-auth-server guides and the sidebar to surface the new content.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| sidebars.ts | Adds the two new vMCP guide pages to the Authentication and authorization section. |
| docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx | Links readers to the new “minting delegated tokens” concepts section for delegation context. |
| docs/toolhive/guides-vmcp/delegate-agent-identity.mdx | New guide documenting RFC 8693 delegation configuration, exchange walkthrough, and troubleshooting. |
| docs/toolhive/guides-vmcp/accept-workload-assertions.mdx | New guide documenting RFC 7523 JWT-bearer grant configuration patterns and troubleshooting. |
| docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx | Adds a delegation context link to the concepts page from the Kubernetes embedded auth server guide. |
| docs/toolhive/concepts/embedded-auth-server.mdx | Adds a new section explaining why delegation exists and linking to the new delegation guide. |
Suppressed comments (5)
docs/toolhive/guides-vmcp/delegate-agent-identity.mdx:252
- Sentence fragment: "Everything else about the exchange." should be merged into the surrounding sentence so the paragraph reads cleanly.
twice) on the second attempt. 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
docs/toolhive/guides-vmcp/delegate-agent-identity.mdx:260
- Section order: these how-to pages are expected to end with "Next steps", then "Related information", then "Troubleshooting" (if present). Here, Troubleshooting appears before Next steps, which makes forward navigation harder.
## Troubleshooting
| Error | Likely 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 `delegateClients[].clientSecretRef` is set and the client authenticated with the matching secret and method. |
docs/toolhive/guides-vmcp/accept-workload-assertions.mdx:31
- Reachability: this guide documents
trustedIssuers[].jwtBearerGrant, which the PR description calls out as not yet in a released ToolHive version and not present in the pinned docs sync (ToolHive v0.43.0 in .github/upstream-projects.yaml:45-48). Add an availability note so readers don't assume it's available in their current install.
docs/toolhive/guides-vmcp/accept-workload-assertions.mdx:142 - Section order: these how-to pages are expected to end with "Next steps", then "Related information", then "Troubleshooting" (if present). Here, Troubleshooting appears before Next steps, which makes forward navigation harder.
## Troubleshooting
Two things vary by issuer and are worth checking first if an exchange fails:
whether the assertion carries a `jti` at all (Entra's `client_credentials`
tokens and plain SPIRE JWT-SVIDs never include one, so ToolHive falls back to
docs/toolhive/guides-vmcp/delegate-agent-identity.mdx:29
- Reachability: this docs repo is currently pinned to ToolHive v0.43.0 (.github/upstream-projects.yaml:45-48), but this guide references fields called out in the PR description as only on newer/unreleased ToolHive versions (e.g.,
actorMatcher,allowMayAct,allowPrivateKeyJWTRegistration). Add a short availability note so readers don't try to follow steps that their installed CRDs don't support yet.
## Overview
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+162
to
+166
| letting a pre-provisioned **delegate client** (typically a coding agent or | ||
| automation workload) to exchange a user's subject token for a new | ||
| ToolHive-issued token that names the user as `sub` and records the delegate | ||
| client as the acting party in `act`, forming the same claim shape described | ||
| above. |
Comment on lines
+9
to
+13
| When an AI agent acts on a user's behalf (reading their calendar, filing a | ||
| ticket, calling a tool through 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: |
Comment on lines
+16
to
+18
| JWT-bearer grant lets an agent use that identity directly to call a tool through | ||
| vMCP: it presents a signed assertion from its identity provider straight to | ||
| ToolHive's token endpoint, and ToolHive exchanges it for a ToolHive token, with |
Fold three explanations from the v0.44.0 release-sync branch into the delegation guide: that a trustedIssuers entry alone doesn't create a usable exchange path without a delegate client to authenticate, why allowedDelegateClients binds an external actor to a specific client, and that "client_id" is a sentinel rather than a claim name. Point at the generated MCPExternalAuthConfig schema reference for the full trustedIssuers field list instead of restating it, and repoint the vMCP and Kubernetes guide cross-references at the delegation guide. Refs #1109 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds two vMCP guides covering the embedded authorization server's agent-identity flows:
delegate-agent-identity.mdx- RFC 8693 token-exchange delegation with a pre-provisioned delegate client, thetrustedIssuersconsent policy (allowedActors/actorMatcher/allowMayAct), a walked-through exchange with the resultingactclaim, and secretlessprivate_key_jwtregistration.accept-workload-assertions.mdx- the RFC 7523 JWT-bearer grant, with per-issuer configuration for Okta, Entra, and SPIFFE/SPIRE.Both are linked from the concepts page and from the vMCP and Kubernetes embedded auth server guides. A new "Minting delegated tokens with delegate clients" section on the concepts page explains why delegation exists and separates minting an
actclaim from reading one.Field names, CEL admission rule messages, token-endpoint error strings, and the delegated token's claim shape were all verified against the ToolHive source rather than written from the CRD schema alone.
Type of change
Related issues/PRs
Refs #1109
Not yet covered, so this does not close the issue:
actorMatcher/allowedActors/allowMayAct/jwtBearerGrant. Those pages are auto-generated and land via the release sync, not by hand.AllowClientAssertionAuth(a delegate client authenticating with a self-issued assertion rather than a static secret). Theprivate_key_jwtsection is adjacent but covers DCR-registered keypairs, which is a different mechanism.Reachability note for reviewers
The three field groups below are on
mainupstream but not in a released ToolHive version (latest is v0.44.0; this site is synced at v0.43.0):trustedIssuers[].jwtBearerGrantand everything under it - the whole basis ofaccept-workload-assertions.mdxactorMatcherallowPrivateKeyJWTRegistration(merging shortly)The RFC 8693 delegation content in
delegate-agent-identity.mdxuses only fields released in v0.44.0. Worth confirming the docs release sync trails the ToolHive release so these pages don't publish ahead of the code being reachable.Submitter checklist
Content and formatting
Navigation
sidebars.ts) updated for added, deleted, reordered, or renamed filesvercel.json- n/a, no pages moved, renamed, or deletedReviewer checklist
Content