From d9869212745946ab5d110577ccf52487416459e2 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 14:57:18 +0000 Subject: [PATCH 1/4] Update stacklok/toolhive to v0.65.0 Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- .github/upstream-projects.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/upstream-projects.yaml b/.github/upstream-projects.yaml index dd5667397..bc7ee351b 100644 --- a/.github/upstream-projects.yaml +++ b/.github/upstream-projects.yaml @@ -64,7 +64,7 @@ projects: - id: toolhive repo: stacklok/toolhive - version: v0.64.0 + version: v0.65.0 # toolhive is a monorepo covering the CLI, the Kubernetes # operator, and the vMCP gateway. It also introduces cross- # cutting features that land in concepts/, integrations/, From 9e4ecaa5823497341197ffa1f0fbeef56b5a38b3 Mon Sep 17 00:00:00 2001 From: "stacklok-octosts[bot]" <327033170+stacklok-octosts[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 14:58:15 +0000 Subject: [PATCH 2/4] Refresh reference assets for toolhive v0.65.0 --- .../toolhive/reference/helm/operator-crds.mdx | 6 +- docs/toolhive/reference/helm/operator.mdx | 18 ++--- static/api-specs/toolhive-api.yaml | 72 +++++++++++++++++-- .../mcpexternalauthconfigs.schema.json | 14 ++-- .../virtualmcpservers.schema.json | 14 ++-- 5 files changed, 92 insertions(+), 32 deletions(-) diff --git a/docs/toolhive/reference/helm/operator-crds.mdx b/docs/toolhive/reference/helm/operator-crds.mdx index 9ab3e7fbf..f318e2650 100644 --- a/docs/toolhive/reference/helm/operator-crds.mdx +++ b/docs/toolhive/reference/helm/operator-crds.mdx @@ -11,9 +11,9 @@ Control CRD installation and preservation with these Helm values. This reference lists values declared in the chart's default `values.yaml`. Templates can also accept optional settings and inherited `global` values. -Chart: `toolhive-operator-crds`. Chart version: `0.64.0`. Source: -[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.64.0/deploy/charts/operator-crds/values.yaml) -at `v0.64.0`. +Chart: `toolhive-operator-crds`. Chart version: `0.65.0`. Source: +[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.65.0/deploy/charts/operator-crds/values.yaml) +at `v0.65.0`. ## Values diff --git a/docs/toolhive/reference/helm/operator.mdx b/docs/toolhive/reference/helm/operator.mdx index 6599af556..c413cf39a 100644 --- a/docs/toolhive/reference/helm/operator.mdx +++ b/docs/toolhive/reference/helm/operator.mdx @@ -10,9 +10,9 @@ Configure the ToolHive operator with these Helm values. This reference lists values declared in the chart's default `values.yaml`. Templates can also accept optional settings and inherited `global` values. -Chart: `toolhive-operator`. Chart version: `0.64.0`. Source: -[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.64.0/deploy/charts/operator/values.yaml) -at `v0.64.0`. +Chart: `toolhive-operator`. Chart version: `0.65.0`. Source: +[`values.yaml`](https://github.com/stacklok/toolhive/blob/v0.65.0/deploy/charts/operator/values.yaml) +at `v0.65.0`. ## Values @@ -73,7 +73,7 @@ features: gc: gogc: 75 gomemlimit: 110MiB -image: ghcr.io/stacklok/toolhive/operator:v0.64.0 +image: ghcr.io/stacklok/toolhive/operator:v0.65.0 imageDiscovery: enabled: false resources: {} @@ -158,8 +158,8 @@ serviceAccount: labels: {} name: toolhive-operator tolerations: [] -toolhiveRunnerImage: ghcr.io/stacklok/toolhive/proxyrunner:v0.64.0 -vmcpImage: ghcr.io/stacklok/toolhive/vmcp:v0.64.0 +toolhiveRunnerImage: ghcr.io/stacklok/toolhive/proxyrunner:v0.65.0 +vmcpImage: ghcr.io/stacklok/toolhive/vmcp:v0.65.0 volumeMounts: [] volumes: [] ``` @@ -318,7 +318,7 @@ Key containing the PEM-encoded CA certificate in the Secret. **Type:** `string` -**Default:** `"ghcr.io/stacklok/toolhive/operator:v0.64.0"` +**Default:** `"ghcr.io/stacklok/toolhive/operator:v0.65.0"` Container image for the operator. @@ -334,7 +334,7 @@ Image pull policy for the operator container and image-discovery containers. **Type:** `string` -**Default:** `"ghcr.io/stacklok/toolhive/proxyrunner:v0.64.0"` +**Default:** `"ghcr.io/stacklok/toolhive/proxyrunner:v0.65.0"` Container image for ToolHive proxy runners created by the operator. @@ -342,7 +342,7 @@ Container image for ToolHive proxy runners created by the operator. **Type:** `string` -**Default:** `"ghcr.io/stacklok/toolhive/vmcp:v0.64.0"` +**Default:** `"ghcr.io/stacklok/toolhive/vmcp:v0.65.0"` Container image for Virtual MCP Server (vMCP) deployments created by the operator. diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml index 7d16c424f..78afd26de 100644 --- a/static/api-specs/toolhive-api.yaml +++ b/static/api-specs/toolhive-api.yaml @@ -283,6 +283,59 @@ components: value; validation rejects refresh_token_max_lifetime without it. type: string type: object + authserver.DelegateClientIDJAG: + description: |- + IDJAG lists the authorization servers this client may ask for an + Identity Assertion JWT Authorization Grant (ID-JAG) for. Valid only with + restricted, with exchange_refresh_tokens.id_jag_max_lifetime set, and with + token exchange enabled. + properties: + targets: + description: |- + Targets are the authorization servers the client may ask for an ID-JAG + for. At least one is required. + items: + $ref: '#/components/schemas/authserver.DelegateClientIDJAGTarget' + type: array + uniqueItems: false + type: object + authserver.DelegateClientIDJAGTarget: + properties: + client_id: + description: ClientID is this client's client_id at the other authorization + server. + type: string + issuer: + description: |- + Issuer is the issuer of the other authorization server. The client sends + it as the request's audience, and it becomes the ID-JAG's aud exactly as + written here. It must be an absolute https URL, or http on a loopback + host, with no query, fragment or userinfo. It must be well-formed: lower-case + scheme and host, no default port (":443" for https, ":80" for http), no dot + segments, empty path segments, unneeded percent-encoding or leading zeros + in the port. One trailing slash is allowed and is kept as written. It must + be unique within the client, and the (issuer, client_id) pair must be + unique across delegate clients; both comparisons ignore one trailing + slash. It must not be this server's issuer, token endpoint or one of its + allowed_audiences; that comparison ignores case in the scheme and host, a + default port and one trailing slash. + type: string + lifetime: + description: |- + Lifetime is how long each ID-JAG lives, as a Go duration string in whole + seconds (e.g. "60s"). Defaults to 60s; at most 300s. + type: string + resources: + description: |- + Resources are the resources behind the other authorization server, such + as an MCP endpoint, that the client may name as the request's resource. + At least one is required. Each must be a valid RFC 8707 resource URI, + listed once. + items: + type: string + type: array + uniqueItems: false + type: object authserver.DelegateClientRunConfig: properties: audiences: @@ -396,6 +449,8 @@ components: uniqueItems: false exchange_refresh_tokens: $ref: '#/components/schemas/authserver.DelegateClientExchangeRefreshTokens' + id_jag: + $ref: '#/components/schemas/authserver.DelegateClientIDJAG' self_issued_subject_tokens: description: |- SelfIssuedSubjectTokens is any or restricted, and is required. With @@ -965,8 +1020,10 @@ components: upstreams: description: |- Upstreams configures connections to upstream Identity Providers for - interactive authorization. It may be empty only when DelegateClients or a - TrustedIssuer with JWTBearerGrant enables token-only operation. + interactive authorization. It may be empty only when token-only operation + is enabled by DelegateClients (also under InboundGrants.TokenExchange), + InboundGrants.SPIFFEClientAuth, or a TrustedIssuer with JWTBearerGrant + (also under InboundGrants.JWTBearer). Multiple upstreams are supported for sequential authorization chains. items: $ref: '#/components/schemas/authserver.UpstreamRunConfig' @@ -989,8 +1046,8 @@ components: authserver.SPIFFEBundleSourceRunConfig: description: |- BundleSource declares exactly one trust-bundle source and is validated for - shape here. The standalone file loader exists, but source initialization - is not wired into SPIFFE authentication. + shape here. Only the file source is loaded in this build; bundle_endpoint + and workload_api are rejected by Validate. properties: endpoint: $ref: '#/components/schemas/authserver.SPIFFEBundleEndpointSourceRunConfig' @@ -5586,8 +5643,11 @@ components: authorization server for this grant; it is NOT a resource/API identifier — a bare resource audience is deliberately not accepted here, that would let any RFC 8707 resource-scoped token satisfy the - grant instead of only tokens minted for this AS. Defaults to - [tokenEndpoint] when empty, preserving prior exact-match behavior. + grant instead of only tokens minted for this AS. When empty, the plain + JWT-bearer grant accepts the token endpoint, and the ID-JAG grant accepts + the token endpoint and this server's issuer identifier, unless the issuer + is also an allowed resource audience. A configured list replaces both + defaults. items: type: string type: array diff --git a/static/api-specs/toolhive-crds/mcpexternalauthconfigs.schema.json b/static/api-specs/toolhive-crds/mcpexternalauthconfigs.schema.json index 16bf37100..86899f647 100644 --- a/static/api-specs/toolhive-crds/mcpexternalauthconfigs.schema.json +++ b/static/api-specs/toolhive-crds/mcpexternalauthconfigs.schema.json @@ -299,7 +299,7 @@ "description": "JWTBearerIssuerPolicyConfig binds RFC 7523 policy to a named trusted issuer.", "properties": { "acceptedAudiences": { - "description": "AcceptedAudiences identifies this authorization server's accepted\nassertion audiences. When omitted, runtime validation defaults to the\ntoken endpoint.", + "description": "AcceptedAudiences identifies this authorization server's accepted\nassertion audiences. When omitted, plain JWT-bearer assertions must name\nthe token endpoint, and ID-JAG assertions may name the token endpoint or\nthis server's issuer identifier, unless the issuer is also an allowed\nresource audience. A configured list replaces these defaults.", "items": { "maxLength": 2048, "minLength": 1, @@ -385,7 +385,7 @@ "spiffeClientAuth": { "description": "SPIFFEClientAuth associates SPIFFE principal patterns with explicit\nOAuth client identities and permissions. A sibling of TokenExchange and\nJWTBearer below, not nested under either: client authentication does\nnot by itself confer a grant. See SPIFFEClientConfig.", "items": { - "description": "SPIFFEClientConfig associates one SPIFFE principal pattern from a declared\ntrust domain with an explicit OAuth client identity and permissions.\nConfiguration is not authentication: configured SPIFFE clients remain\nnon-public OAuth clients without a secret until live SPIFFE credential\nvalidation is implemented (see SPIFFETrustDomainConfig's doc comment).\n\nGrantTypes is deliberately not exposed here: the runtime only accepts\nexactly the RFC 8693 token-exchange grant for a SPIFFE client\n(validateSPIFFEGrants in pkg/authserver/spiffe_trust.go), so the converter\nalways supplies it instead of letting it be configured.", + "description": "SPIFFEClientConfig associates one SPIFFE principal pattern from a declared\ntrust domain with an explicit OAuth client identity and permissions.\nDeclaring a client does not grant access by itself. SPIFFE clients\nauthenticate with a JWT-SVID or an X.509-SVID and have no client secret.\nTrust material comes from the declared bundle source (see\nSPIFFETrustDomainConfig's doc comment).\n\nGrantTypes is deliberately not exposed here: the runtime only accepts\nexactly the RFC 8693 token-exchange grant for a SPIFFE client\n(validateSPIFFEGrants in pkg/authserver/spiffe_trust.go), so the converter\nalways supplies it instead of letting it be configured.", "properties": { "audiences": { "description": "Audiences are RFC 8693 token audiences this association may request.", @@ -707,12 +707,12 @@ "x-kubernetes-list-type": "atomic" }, "spiffeTrustDomains": { - "description": "SPIFFETrustDomains declares SPIFFE trust domains for\ninboundGrants.spiffeClientAuth associations. See SPIFFETrustDomainConfig's\ndoc comment for why declaring a domain does not by itself enable\nauthentication in this build.", + "description": "SPIFFETrustDomains declares SPIFFE trust domains for\ninboundGrants.spiffeClientAuth associations. Each declaration must be\nreferenced by an inboundGrants.spiffeClientAuth entry.", "items": { - "description": "SPIFFETrustDomainConfig declares one SPIFFE trust domain accepted by the\nembedded authorization server. Configuration is not authentication: no\nlive X.509-SVID or JWT-SVID validation exists yet, so a declared trust\ndomain does not by itself let any workload authenticate — RunConfig.Validate\n(pkg/authserver/config.go) currently hard-rejects any non-empty\nspiffeTrustDomains at authserver startup via validateSPIFFENotYetEnforced,\na deliberate placeholder until real SVID verification lands.", + "description": "SPIFFETrustDomainConfig declares one SPIFFE trust domain accepted by the\nembedded authorization server. A declared domain becomes usable only after\nthe configured source supplies trust material during auth-server startup.", "properties": { "bundleSource": { - "description": "BundleSource declares exactly one trust-bundle source and is validated for\nshape here. The standalone file loader exists, but is not wired into SPIFFE\nauthentication.", + "description": "BundleSource declares exactly one trust-bundle source and is validated for\nshape here. Only the file source is loaded in this build; bundle_endpoint\nand workload_api are rejected when the auth-server configuration is\nvalidated.", "properties": { "endpoint": { "description": "Endpoint declares a HTTPS SPIFFE Bundle Endpoint. Required when Type is\n\"bundle_endpoint\".", @@ -1233,7 +1233,7 @@ "description": "JWTBearerGrant enables the plain RFC 7523 JWT-bearer grant for this\nissuer. It is independent of RFC 8693 delegation policy.\nThis legacy field is deprecated; configure RFC 7523 policy under\ninboundGrants.jwtBearer.issuerPolicies.", "properties": { "acceptedAudiences": { - "description": "AcceptedAudiences identifies this authorization server's accepted\nassertion audiences. When omitted, runtime validation defaults to the\ntoken endpoint.", + "description": "AcceptedAudiences identifies this authorization server's accepted\nassertion audiences. When omitted, plain JWT-bearer assertions must name\nthe token endpoint, and ID-JAG assertions may name the token endpoint or\nthis server's issuer identifier, unless the issuer is also an allowed\nresource audience. A configured list replaces these defaults.", "items": { "maxLength": 2048, "minLength": 1, @@ -1345,7 +1345,7 @@ "x-kubernetes-list-type": "atomic" }, "upstreamProviders": { - "description": "UpstreamProviders configures connections to upstream Identity Providers.\nWhen configured, the embedded auth server delegates interactive authentication\nto these providers. It may be omitted only when delegateClients or a trusted\nissuer with jwtBearerGrant enables token-only operation.\nMCPServer and MCPRemoteProxy support a single upstream; VirtualMCPServer supports multiple.", + "description": "UpstreamProviders configures connections to upstream Identity Providers.\nWhen configured, the embedded auth server delegates interactive authentication\nto these providers. It may be omitted only when token-only operation is\nenabled by delegateClients (also under inboundGrants.tokenExchange),\ninboundGrants.spiffeClientAuth, or a trusted issuer with jwtBearerGrant\n(also under inboundGrants.jwtBearer).\nMCPServer and MCPRemoteProxy support a single upstream; VirtualMCPServer supports multiple.", "items": { "description": "UpstreamProviderConfig defines configuration for an upstream Identity Provider.\n\nExactly one of OIDCConfig or OAuth2Config must be set and must match the\ndeclared Type: oidc-typed providers set OIDCConfig, oauth2-typed providers\nset OAuth2Config. The CEL rule below enforces the pairing at admission; the\nmatching Go-level check in validateUpstreamProvider provides defense-in-depth\nfor stored objects.\n\nThe rule is structured as a chain of equality checks ending in an explicit\n`false`, so adding a new UpstreamProviderType value without extending this\nrule fails admission instead of silently demanding the OAuth2 shape. When\nadding a new type, extend both this rule and validateUpstreamProvider.", "properties": { diff --git a/static/api-specs/toolhive-crds/virtualmcpservers.schema.json b/static/api-specs/toolhive-crds/virtualmcpservers.schema.json index 71a5b2fae..47e125152 100644 --- a/static/api-specs/toolhive-crds/virtualmcpservers.schema.json +++ b/static/api-specs/toolhive-crds/virtualmcpservers.schema.json @@ -190,7 +190,7 @@ "description": "JWTBearerIssuerPolicyConfig binds RFC 7523 policy to a named trusted issuer.", "properties": { "acceptedAudiences": { - "description": "AcceptedAudiences identifies this authorization server's accepted\nassertion audiences. When omitted, runtime validation defaults to the\ntoken endpoint.", + "description": "AcceptedAudiences identifies this authorization server's accepted\nassertion audiences. When omitted, plain JWT-bearer assertions must name\nthe token endpoint, and ID-JAG assertions may name the token endpoint or\nthis server's issuer identifier, unless the issuer is also an allowed\nresource audience. A configured list replaces these defaults.", "items": { "maxLength": 2048, "minLength": 1, @@ -276,7 +276,7 @@ "spiffeClientAuth": { "description": "SPIFFEClientAuth associates SPIFFE principal patterns with explicit\nOAuth client identities and permissions. A sibling of TokenExchange and\nJWTBearer below, not nested under either: client authentication does\nnot by itself confer a grant. See SPIFFEClientConfig.", "items": { - "description": "SPIFFEClientConfig associates one SPIFFE principal pattern from a declared\ntrust domain with an explicit OAuth client identity and permissions.\nConfiguration is not authentication: configured SPIFFE clients remain\nnon-public OAuth clients without a secret until live SPIFFE credential\nvalidation is implemented (see SPIFFETrustDomainConfig's doc comment).\n\nGrantTypes is deliberately not exposed here: the runtime only accepts\nexactly the RFC 8693 token-exchange grant for a SPIFFE client\n(validateSPIFFEGrants in pkg/authserver/spiffe_trust.go), so the converter\nalways supplies it instead of letting it be configured.", + "description": "SPIFFEClientConfig associates one SPIFFE principal pattern from a declared\ntrust domain with an explicit OAuth client identity and permissions.\nDeclaring a client does not grant access by itself. SPIFFE clients\nauthenticate with a JWT-SVID or an X.509-SVID and have no client secret.\nTrust material comes from the declared bundle source (see\nSPIFFETrustDomainConfig's doc comment).\n\nGrantTypes is deliberately not exposed here: the runtime only accepts\nexactly the RFC 8693 token-exchange grant for a SPIFFE client\n(validateSPIFFEGrants in pkg/authserver/spiffe_trust.go), so the converter\nalways supplies it instead of letting it be configured.", "properties": { "audiences": { "description": "Audiences are RFC 8693 token audiences this association may request.", @@ -598,12 +598,12 @@ "x-kubernetes-list-type": "atomic" }, "spiffeTrustDomains": { - "description": "SPIFFETrustDomains declares SPIFFE trust domains for\ninboundGrants.spiffeClientAuth associations. See SPIFFETrustDomainConfig's\ndoc comment for why declaring a domain does not by itself enable\nauthentication in this build.", + "description": "SPIFFETrustDomains declares SPIFFE trust domains for\ninboundGrants.spiffeClientAuth associations. Each declaration must be\nreferenced by an inboundGrants.spiffeClientAuth entry.", "items": { - "description": "SPIFFETrustDomainConfig declares one SPIFFE trust domain accepted by the\nembedded authorization server. Configuration is not authentication: no\nlive X.509-SVID or JWT-SVID validation exists yet, so a declared trust\ndomain does not by itself let any workload authenticate — RunConfig.Validate\n(pkg/authserver/config.go) currently hard-rejects any non-empty\nspiffeTrustDomains at authserver startup via validateSPIFFENotYetEnforced,\na deliberate placeholder until real SVID verification lands.", + "description": "SPIFFETrustDomainConfig declares one SPIFFE trust domain accepted by the\nembedded authorization server. A declared domain becomes usable only after\nthe configured source supplies trust material during auth-server startup.", "properties": { "bundleSource": { - "description": "BundleSource declares exactly one trust-bundle source and is validated for\nshape here. The standalone file loader exists, but is not wired into SPIFFE\nauthentication.", + "description": "BundleSource declares exactly one trust-bundle source and is validated for\nshape here. Only the file source is loaded in this build; bundle_endpoint\nand workload_api are rejected when the auth-server configuration is\nvalidated.", "properties": { "endpoint": { "description": "Endpoint declares a HTTPS SPIFFE Bundle Endpoint. Required when Type is\n\"bundle_endpoint\".", @@ -1124,7 +1124,7 @@ "description": "JWTBearerGrant enables the plain RFC 7523 JWT-bearer grant for this\nissuer. It is independent of RFC 8693 delegation policy.\nThis legacy field is deprecated; configure RFC 7523 policy under\ninboundGrants.jwtBearer.issuerPolicies.", "properties": { "acceptedAudiences": { - "description": "AcceptedAudiences identifies this authorization server's accepted\nassertion audiences. When omitted, runtime validation defaults to the\ntoken endpoint.", + "description": "AcceptedAudiences identifies this authorization server's accepted\nassertion audiences. When omitted, plain JWT-bearer assertions must name\nthe token endpoint, and ID-JAG assertions may name the token endpoint or\nthis server's issuer identifier, unless the issuer is also an allowed\nresource audience. A configured list replaces these defaults.", "items": { "maxLength": 2048, "minLength": 1, @@ -1236,7 +1236,7 @@ "x-kubernetes-list-type": "atomic" }, "upstreamProviders": { - "description": "UpstreamProviders configures connections to upstream Identity Providers.\nWhen configured, the embedded auth server delegates interactive authentication\nto these providers. It may be omitted only when delegateClients or a trusted\nissuer with jwtBearerGrant enables token-only operation.\nMCPServer and MCPRemoteProxy support a single upstream; VirtualMCPServer supports multiple.", + "description": "UpstreamProviders configures connections to upstream Identity Providers.\nWhen configured, the embedded auth server delegates interactive authentication\nto these providers. It may be omitted only when token-only operation is\nenabled by delegateClients (also under inboundGrants.tokenExchange),\ninboundGrants.spiffeClientAuth, or a trusted issuer with jwtBearerGrant\n(also under inboundGrants.jwtBearer).\nMCPServer and MCPRemoteProxy support a single upstream; VirtualMCPServer supports multiple.", "items": { "description": "UpstreamProviderConfig defines configuration for an upstream Identity Provider.\n\nExactly one of OIDCConfig or OAuth2Config must be set and must match the\ndeclared Type: oidc-typed providers set OIDCConfig, oauth2-typed providers\nset OAuth2Config. The CEL rule below enforces the pairing at admission; the\nmatching Go-level check in validateUpstreamProvider provides defense-in-depth\nfor stored objects.\n\nThe rule is structured as a chain of equality checks ending in an explicit\n`false`, so adding a new UpstreamProviderType value without extending this\nrule fails admission instead of silently demanding the OAuth2 shape. When\nadding a new type, extend both this rule and validateUpstreamProvider.", "properties": { From 4cc116dc03e4f76b0ba8742e61abc56411f367e0 Mon Sep 17 00:00:00 2001 From: "stacklok-octosts[bot]" <327033170+stacklok-octosts[bot]@users.noreply.github.com> Date: Sat, 14 Nov 2026 05:41:46 +0000 Subject: [PATCH 3/4] Apply prettier and eslint fixups to skill output --- .../guides-k8s/embedded-auth-server-k8s.mdx | 20 +- docs/toolhive/guides-k8s/logging.mdx | 56 ++--- .../accept-workload-assertions.mdx | 36 +-- docs/toolhive/guides-vmcp/audit-logging.mdx | 31 +-- .../guides-vmcp/delegate-agent-identity.mdx | 220 ++++++++++++++++-- .../guides-vmcp/embedded-auth-server-vmcp.mdx | 21 +- 6 files changed, 276 insertions(+), 108 deletions(-) diff --git a/docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx b/docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx index 208f2f63d..4efac9263 100644 --- a/docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx +++ b/docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx @@ -220,6 +220,7 @@ with a generic "authorization header required" error. | `cimd` | Optional Client ID Metadata Document (CIMD) configuration. When `cimd.enabled` is `true`, the auth server accepts HTTPS URLs as `client_id` values and resolves them via CIMD, letting clients (for example, VS Code) authenticate without prior Dynamic Client Registration. See [Enable CIMD for zero-registration clients](#enable-cimd-for-zero-registration-clients). | | `baselineClientScopes` | Optional list of OAuth 2.0 scopes merged into every DCR-registered client's scope set. Use this when MCP clients register with a narrowed `scope` field but then request wider scopes at `/oauth/authorize`. See [Enable baseline scopes for DCR clients](#enable-baseline-scopes-for-dcr-clients). | | `tlsListener` | Optional. Serves the authorization server's OAuth endpoints over HTTPS on port 8443, using a certificate and private key from a Secret. See [Serve the authorization server over TLS](#serve-the-authorization-server-over-tls). | +| `spiffeTrustDomains` | Optional. Declares SPIFFE trust domains and their trust bundles, used with `inboundGrants.spiffeClientAuth` to let SPIFFE workloads authenticate with JWT-SVIDs or X.509-SVIDs for token exchange. See [Authenticate workloads with SPIFFE SVIDs](../guides-vmcp/delegate-agent-identity.mdx#authenticate-workloads-with-spiffe-svids). | | `disableUpstreamTokenInjection` | Optional. When `true`, the embedded auth server authenticates clients normally but the proxy strips `Authorization`, `Cookie`, and `Proxy-Authorization` from forwarded requests instead of swapping the JWT for an upstream token. Use this for public backends (such as documentation servers) that you still want to gate behind client auth. Cannot be combined with `tokenExchange`, `awsSts`, or OBO (Stacklok Enterprise) on the same workload, since each would re-add credentials after the strip. | ## Step 5: Create the MCPOIDCConfig and MCPServer resources @@ -440,6 +441,10 @@ Because the TLS listener owns port 8443, set the workload's `proxyPort` to a different port. If both use 8443, the operator marks the workload `Failed` and reports the conflict in its status conditions. +The TLS listener is also where SPIFFE workloads authenticate with X.509-SVIDs. +See +[Authenticate workloads with SPIFFE SVIDs](../guides-vmcp/delegate-agent-identity.mdx#authenticate-workloads-with-spiffe-svids). + A VirtualMCPServer accepts the same block at `spec.authServerConfig.tlsListener`. See [Serve the authorization server over TLS](../guides-vmcp/embedded-auth-server-vmcp.mdx#serve-the-authorization-server-over-tls) @@ -475,9 +480,9 @@ spec: `cacheMaxSize` sets the LRU cache capacity (default `256`), and `cacheFallbackTtl` sets the TTL applied to every cached entry as a Go duration -string (default `5m`). The CIMD fetcher doesn't yet honor `Cache-Control` -headers; every cached document uses the fallback TTL. When disabled (the -default), only DCR-registered `client_id` values are accepted. +string (default `5m`). The CIMD fetcher ignores `Cache-Control` headers, so +every cached document uses the fallback TTL. When disabled (the default), only +DCR-registered `client_id` values are accepted. If you also set `baselineClientScopes`, those scopes apply to CIMD-resolved clients too. Because CIMD clients can be resolved from arbitrary HTTPS URLs, @@ -508,6 +513,15 @@ The fetcher also applies SSRF protection: DNS resolution runs before dialing, private IP ranges are blocked, redirects are not followed, and each fetch is subject to a five-second timeout and a 10 KB response cap. +When a cached document expires and the re-fetch fails for a transient reason (a +connection, DNS, or TLS error, a timeout, a truncated body, or an HTTP 5xx, 408, +or 429 response), the embedded authorization server keeps serving the expired +document for up to the configured access token lifespan past its expiry, so a +brief outage at the client's metadata host doesn't break authentication. Each +lookup during that window retries the fetch first. A definitive failure, such as +an HTTP 404, a malformed document, or a document that fails the rules above, +evicts the cached entry and the client fails with `invalid_client`. + For the two-layer trust model behind CIMD (why the upstream IdP never sees the client's CIMD URL), see [Client ID Metadata Document (CIMD)](../concepts/embedded-auth-server.mdx#client-id-metadata-document-cimd). diff --git a/docs/toolhive/guides-k8s/logging.mdx b/docs/toolhive/guides-k8s/logging.mdx index a1d798d81..1be5f37b8 100644 --- a/docs/toolhive/guides-k8s/logging.mdx +++ b/docs/toolhive/guides-k8s/logging.mdx @@ -225,33 +225,35 @@ configured, the `user_id` field is set to `local`. #### Audit log fields -| Field | Type | Description | -| ---------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `time` | string | Timestamp when the log was generated | -| `level` | string | Log level (`AUDIT` for audit events) | -| `msg` | string | Always "audit_event" for audit logs | -| `audit_id` | string | Unique identifier for the audit event | -| `type` | string | Type of MCP operation (see event types below) | -| `logged_at` | string | UTC timestamp of the event | -| `outcome` | string | Result of the operation: `success`, `failure`, `error`, `denied` (authorization denial), or `application_error` (transport succeeded but the JSON-RPC response reported an error) | -| `component` | string | Name of the MCP server | -| `source` | object | Request source information | -| `source.type` | string | Source type (e.g., "network") | -| `source.value` | string | Source identifier (e.g., IP address) | -| `source.extra` | object | Additional source metadata | -| `subjects` | object | User and identity information | -| `subjects.user` | string | User display name (from JWT claims: name, preferred_username, or email) | -| `subjects.user_id` | string | User identifier (from JWT sub claim) | -| `subjects.client_name` | string | Client application name (optional, from JWT claims) | -| `subjects.client_version` | string | Client version (optional, from JWT claims) | -| `target` | object | Target resource information | -| `target.endpoint` | string | API endpoint path | -| `target.method` | string | MCP method called | -| `target.name` | string | Tool or resource name | -| `target.type` | string | Target type (e.g., "tool") | -| `metadata` | object | Additional metadata | -| `metadata.extra.duration_ms` | number | Operation duration in milliseconds | -| `metadata.extra.transport` | string | Transport protocol used | +| Field | Type | Description | +| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `time` | string | Timestamp when the log was generated | +| `level` | string | Log level (`AUDIT` for audit events) | +| `msg` | string | Always "audit_event" for audit logs | +| `audit_id` | string | Unique identifier for the audit event | +| `type` | string | Type of MCP operation (see event types below) | +| `logged_at` | string | UTC timestamp of the event | +| `outcome` | string | Result of the operation: `success`, `failure`, `error`, `denied` (authorization denial), or `application_error` (transport succeeded but the JSON-RPC response reported an error) | +| `component` | string | Name of the MCP server | +| `source` | object | Request source information | +| `source.type` | string | Source type (e.g., "network") | +| `source.value` | string | Source identifier (e.g., IP address) | +| `source.extra` | object | Additional source metadata | +| `subjects` | object | User and identity information | +| `subjects.user` | string | User display name (from JWT claims: name, preferred_username, or email) | +| `subjects.user_id` | string | User identifier (from JWT sub claim) | +| `subjects.client_name` | string | Client application name (optional, from JWT claims) | +| `subjects.client_version` | string | Client version (optional, from JWT claims) | +| `target` | object | Target resource information | +| `target.endpoint` | string | API endpoint path | +| `target.method` | string | MCP method called | +| `target.name` | string | Tool or resource name | +| `target.type` | string | Target type (e.g., "tool") | +| `metadata` | object | Additional metadata | +| `metadata.extra.duration_ms` | number | Operation duration in milliseconds | +| `metadata.extra.transport` | string | Transport protocol used | +| `metadata.extra.trace_id` | string | W3C trace ID (32 hex characters) of the request's span. Present only when the request carries a valid trace context (OpenTelemetry tracing enabled or an inbound `traceparent` header) | +| `metadata.extra.span_id` | string | W3C span ID (16 hex characters) of the request's span. Present under the same conditions as `trace_id` | #### Audit event types diff --git a/docs/toolhive/guides-vmcp/accept-workload-assertions.mdx b/docs/toolhive/guides-vmcp/accept-workload-assertions.mdx index 80464fd59..ad68ba153 100644 --- a/docs/toolhive/guides-vmcp/accept-workload-assertions.mdx +++ b/docs/toolhive/guides-vmcp/accept-workload-assertions.mdx @@ -127,38 +127,10 @@ inboundGrants: unrelated to the JWT-bearer grant; an issuer used only for `inboundGrants.jwtBearer` needs none of them. -:::note[`upstreamProviders` is still required today] - -`EmbeddedAuthServerConfig.upstreamProviders` is optional at the CRD level when a -trusted issuer with a JWT-bearer grant is configured, but the operator's -reconcile-time validation doesn't yet recognize `inboundGrants.jwtBearer`-only -configuration as satisfying that requirement (it only checks the legacy -per-issuer `jwtBearerGrant` field). Until that's fixed, a JWT-bearer-only -`VirtualMCPServer` needs a placeholder `upstreamProviders` entry. ToolHive never -contacts this endpoint or uses its credentials, so any syntactically valid -OAuth2 endpoint works: - -```yaml title="Placeholder upstream (workaround)" -upstreamProviders: - - name: unused - type: oauth2 - oauth2Config: - authorizationEndpoint: 'https://example.invalid/authorize' - tokenEndpoint: 'https://example.invalid/token' - clientId: 'unused' - clientSecretRef: - name: unused-upstream-secret - key: client-secret - scopes: - - openid -``` - -Without it, the `VirtualMCPServer` fails to become `Ready` with: -`auth server requires at least one upstream unless delegate clients or a trusted issuer with JWT bearer grant is configured`. -Remove the placeholder once the validator is updated to normalize -`inboundGrants` before checking. - -::: +A JWT-bearer-only configuration doesn't need `upstreamProviders`: when you omit +it, the authorization server runs in token-only mode and issues tokens only +through the grants you configure. A VirtualMCPServer with no `upstreamProviders` +can't also set `incomingAuth.authzConfig`. ## Request a token diff --git a/docs/toolhive/guides-vmcp/audit-logging.mdx b/docs/toolhive/guides-vmcp/audit-logging.mdx index 5d67491aa..6b05ff868 100644 --- a/docs/toolhive/guides-vmcp/audit-logging.mdx +++ b/docs/toolhive/guides-vmcp/audit-logging.mdx @@ -217,21 +217,22 @@ Each audit event is a structured JSON object with these fields: ### Field descriptions -| Field | Description | -| ----------- | --------------------------------------------------------------------- | -| `time` | Timestamp when the log was generated | -| `level` | Log level (`AUDIT` for audit events) | -| `msg` | Always "audit_event" for audit logs | -| `audit_id` | Unique identifier for this audit event | -| `type` | Event classification (what happened) | -| `logged_at` | UTC timestamp when the event occurred | -| `outcome` | Result (`success`, `failure`, `error`, `denied`, `application_error`) | -| `component` | System component that generated the event | -| `source` | Request origin (IP address, user agent) | -| `subjects` | Identity information (user, client) | -| `target` | Resource or operation targeted | -| `metadata` | Additional context (duration_ms, transport, backend_name) | -| `data` | Optional request and response payloads | +| Field | Description | +| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `time` | Timestamp when the log was generated | +| `level` | Log level (`AUDIT` for audit events) | +| `msg` | Always "audit_event" for audit logs | +| `audit_id` | Unique identifier for this audit event | +| `type` | Event classification (what happened) | +| `logged_at` | UTC timestamp when the event occurred | +| `outcome` | Result (`success`, `failure`, `error`, `denied`, `application_error`) | +| `component` | System component that generated the event | +| `source` | Request origin (IP address, user agent) | +| `subjects` | Identity information (user, client) | +| `target` | Resource or operation targeted | +| `metadata` | Additional context (duration_ms, transport, backend_name) | +| `metadata.extra.trace_id`, `metadata.extra.span_id` | W3C trace and span IDs of the request, present when the request carries a valid trace context (OpenTelemetry tracing enabled or an inbound `traceparent` header). Use them to jump from an audit event to its trace. | +| `data` | Optional request and response payloads | :::note[Audit events use a custom log level] diff --git a/docs/toolhive/guides-vmcp/delegate-agent-identity.mdx b/docs/toolhive/guides-vmcp/delegate-agent-identity.mdx index c38a5765b..28c3ed780 100644 --- a/docs/toolhive/guides-vmcp/delegate-agent-identity.mdx +++ b/docs/toolhive/guides-vmcp/delegate-agent-identity.mdx @@ -1,8 +1,8 @@ --- title: Delegate agent identity with token exchange description: - Configure RFC 8693 token-exchange delegation so a pre-provisioned agent can - act on behalf of a user. + Configure RFC 8693 token-exchange delegation so an agent, authenticated as a + pre-provisioned client or a SPIFFE workload, can act on behalf of a user. --- When an AI agent acts on a user's behalf (reading their calendar, filing a @@ -15,12 +15,13 @@ one that names both the user and the agent acting for them. :::info -The fields covered here (`trustedIssuers` and `inboundGrants.tokenExchange`) 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 +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](../guides-k8s/embedded-auth-server-k8s.mdx). ::: @@ -269,11 +270,17 @@ 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 expired -assertion, an `nbf` or `iat` in the future, or a lifetime longer than the server -allows. A request that sets `client_assertion_type` but omits `client_assertion` -gets HTTP 400 `invalid_request`. +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 @@ -290,6 +297,170 @@ 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](./accept-workload-assertions.mdx) 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`: + +```bash +kubectl create configmap spiffe-trust-bundle \ + --namespace toolhive-system \ + --from-file=bundle.json=./bundle.json +``` + +Then reference it from the VirtualMCPServer: + +```yaml title="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: + +| Field | Description | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | Required. A local name that `spiffeClientAuth[].trustDomainRef` refers to. Every declared trust domain must be referenced. | +| `trustDomain` | Required. The SPIFFE trust domain, such as `example.org`. | +| `methods` | Required. The authentication methods this domain allows: `spiffe_jwt`, `spiffe_x509`, or both. | +| `bundleSource.type` | Required. 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: + +| Field | Description | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `trustDomainRef` | Required. The `name` of a `spiffeTrustDomains` entry. | +| `principalPattern` | Required. An exact SPIFFE ID, or one ending in `/*` to match every ID below that path. It must start with `spiffe:///`. Patterns must not overlap. | +| `clientId` | Required. The OAuth client ID that matching workloads authenticate as. It must be unique and must not match a `delegateClients[].clientId`. | +| `methods` | Required. `spiffe_jwt`, `spiffe_x509`, or both. Must be a subset of the trust domain's `methods`. `spiffe_x509` requires `tlsListener` and an `https://` issuer. | +| `audiences` | Required. The RFC 8693 audiences this client may request. | +| `scopes` | Required. The scopes this client may request. | +| `resources` | Optional. 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: + +```bash title="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=" \ + --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=" +``` + +`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: + +```bash title="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=" \ + --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 + +The subject token a SPIFFE client exchanges is a ToolHive-issued access token. +ToolHive accepts it when the token's `client_id` is the SPIFFE client's +`clientId`, or when its `may_act.sub` names that `clientId`, and when its `aud` +includes the audience the client requests. The issued token records the SPIFFE +client in `act.sub`, using the configured `clientId`; the SPIFFE ID itself +doesn't appear in the token. + ## Next steps - [Accept workload assertions with the JWT-bearer grant](./accept-workload-assertions.mdx) @@ -310,14 +481,17 @@ must register again. ## 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 `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` client | The `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 valid against the server clock, 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`. | -| CRD rejected: `issuerPolicies[]: allowedDelegateClients: Required value` | An `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. | +| 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 `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` client | The `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-SVID | The 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-SVID | Check 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 supported` | Set `bundleSource.type: file` and supply the trust bundle through a ConfigMap. The same applies to `workload_api`. | +| CRD rejected: `issuerPolicies[]: allowedDelegateClients: Required value` | An `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. | diff --git a/docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx b/docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx index 8accffd3e..f294eae8d 100644 --- a/docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx +++ b/docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx @@ -365,15 +365,16 @@ but do not use CIMD. Client-side DCR does not require configuration. ### Choose a way to get a token -The embedded authorization server supports four ways a caller can get a +The embedded authorization server supports five ways a caller can get a ToolHive-issued token, each suited to a different trust relationship: -| Pattern | Who authenticates | Result | -| --------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- | -| [Confidential DCR](#allow-confidential-dcr-clients) | A client self-registers and gets a `client_secret` | The client acts as itself; no delegation | -| [Backend token exchange](../concepts/backend-auth.mdx#token-exchange) | A client presents its own token to a backend IdP | The client's own identity, re-scoped to a backend audience | -| [RFC 8693 delegate-client exchange](./delegate-agent-identity.mdx) | A pre-provisioned client presents a user's subject token | A token naming the user, with the agent recorded as the acting party (`act`) | -| [RFC 7523 JWT-bearer grant](./accept-workload-assertions.mdx) | No client at all; the assertion itself is the credential | A token naming the workload; no delegation, no pre-registered client | +| Pattern | Who authenticates | Result | +| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | +| [Confidential DCR](#allow-confidential-dcr-clients) | A client self-registers and gets a `client_secret` | The client acts as itself; no delegation | +| [Backend token exchange](../concepts/backend-auth.mdx#token-exchange) | A client presents its own token to a backend IdP | The client's own identity, re-scoped to a backend audience | +| [RFC 8693 delegate-client exchange](./delegate-agent-identity.mdx) | A pre-provisioned client presents a user's subject token | A token naming the user, with the agent recorded as the acting party (`act`) | +| [SPIFFE client exchange](./delegate-agent-identity.mdx#authenticate-workloads-with-spiffe-svids) | A SPIFFE workload authenticates with its SVID and presents a ToolHive-issued subject token | A token naming the subject, with the workload's configured client ID as the acting party (`act`) | +| [RFC 7523 JWT-bearer grant](./accept-workload-assertions.mdx) | No client at all; the assertion itself is the credential | A token naming the workload; no delegation, no pre-registered client | ### Enable CIMD for zero-registration clients @@ -392,7 +393,11 @@ spec: | `cimd.cacheMaxSize` | `256` | Optional maximum number of CIMD documents in the LRU cache. | | `cimd.cacheFallbackTtl` | `5m` | Optional Go duration applied to every cached CIMD document. | -The cache defaults are suitable for most deployments. +The cache defaults are suitable for most deployments. If a cached document +expires and the re-fetch fails for a transient reason, such as a timeout or an +HTTP 5xx response, ToolHive keeps serving the expired document for up to the +access token lifespan past its expiry. A definitive failure, such as an HTTP 404 +or an invalid document, evicts the entry. For an explanation of how ToolHive resolves CIMD documents and why the OAuth provider never sees the MCP client's CIMD URL, see From 66ed7bce567176ebe6bb92d847c2597da4dfe230 Mon Sep 17 00:00:00 2001 From: Jakub Hrozek Date: Sat, 14 Nov 2026 17:23:31 +0100 Subject: [PATCH 4/4] Document trusted issuers for SPIFFE subject tokens SPIFFE clients can exchange subject tokens from a trusted external issuer, not only from ToolHive. The delegate agent identity guide described only the ToolHive-issued case, so readers configuring an external issuer had no guidance on the policy fields needed. Describe both cases, link to the issuer policy setup, and warn that allowedDelegateClients set to ["*"] admits every SPIFFE client. Update the embedded auth server pattern table to match. Co-Authored-By: Claude Haiku 5.5 --- .../guides-vmcp/delegate-agent-identity.mdx | 32 +++++++++++++++---- .../guides-vmcp/embedded-auth-server-vmcp.mdx | 14 ++++---- 2 files changed, 33 insertions(+), 13 deletions(-) diff --git a/docs/toolhive/guides-vmcp/delegate-agent-identity.mdx b/docs/toolhive/guides-vmcp/delegate-agent-identity.mdx index 28c3ed780..ed221615c 100644 --- a/docs/toolhive/guides-vmcp/delegate-agent-identity.mdx +++ b/docs/toolhive/guides-vmcp/delegate-agent-identity.mdx @@ -454,12 +454,32 @@ instead. ### Subject tokens for SPIFFE clients -The subject token a SPIFFE client exchanges is a ToolHive-issued access token. -ToolHive accepts it when the token's `client_id` is the SPIFFE client's -`clientId`, or when its `may_act.sub` names that `clientId`, and when its `aud` -includes the audience the client requests. The issued token records the SPIFFE -client in `act.sub`, using the configured `clientId`; the SPIFFE ID itself -doesn't appear in the token. +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](#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 diff --git a/docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx b/docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx index f294eae8d..7580f19bc 100644 --- a/docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx +++ b/docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx @@ -368,13 +368,13 @@ but do not use CIMD. Client-side DCR does not require configuration. The embedded authorization server supports five ways a caller can get a ToolHive-issued token, each suited to a different trust relationship: -| Pattern | Who authenticates | Result | -| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | -| [Confidential DCR](#allow-confidential-dcr-clients) | A client self-registers and gets a `client_secret` | The client acts as itself; no delegation | -| [Backend token exchange](../concepts/backend-auth.mdx#token-exchange) | A client presents its own token to a backend IdP | The client's own identity, re-scoped to a backend audience | -| [RFC 8693 delegate-client exchange](./delegate-agent-identity.mdx) | A pre-provisioned client presents a user's subject token | A token naming the user, with the agent recorded as the acting party (`act`) | -| [SPIFFE client exchange](./delegate-agent-identity.mdx#authenticate-workloads-with-spiffe-svids) | A SPIFFE workload authenticates with its SVID and presents a ToolHive-issued subject token | A token naming the subject, with the workload's configured client ID as the acting party (`act`) | -| [RFC 7523 JWT-bearer grant](./accept-workload-assertions.mdx) | No client at all; the assertion itself is the credential | A token naming the workload; no delegation, no pre-registered client | +| Pattern | Who authenticates | Result | +| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | +| [Confidential DCR](#allow-confidential-dcr-clients) | A client self-registers and gets a `client_secret` | The client acts as itself; no delegation | +| [Backend token exchange](../concepts/backend-auth.mdx#token-exchange) | A client presents its own token to a backend IdP | The client's own identity, re-scoped to a backend audience | +| [RFC 8693 delegate-client exchange](./delegate-agent-identity.mdx) | A pre-provisioned client presents a user's subject token | A token naming the user, with the agent recorded as the acting party (`act`) | +| [SPIFFE client exchange](./delegate-agent-identity.mdx#authenticate-workloads-with-spiffe-svids) | A SPIFFE workload authenticates with its SVID and presents a subject token from ToolHive or a trusted issuer | A token naming the subject, with the workload's configured client ID as the acting party (`act`) | +| [RFC 7523 JWT-bearer grant](./accept-workload-assertions.mdx) | No client at all; the assertion itself is the credential | A token naming the workload; no delegation, no pre-registered client | ### Enable CIMD for zero-registration clients