Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/upstream-projects.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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/,
Expand Down
20 changes: 17 additions & 3 deletions docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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).
Expand Down
56 changes: 29 additions & 27 deletions docs/toolhive/guides-k8s/logging.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
36 changes: 4 additions & 32 deletions docs/toolhive/guides-vmcp/accept-workload-assertions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading
Loading