Update stacklok/toolhive to v0.27.2 (#867)

renovate[bot] · github-actions[bot] · jhrozek · web-flow · commit 01ade9da9c7b · 2026-05-13T10:13:49.000-04:00
* Update stacklok/toolhive to v0.27.2

Signed-off-by: renovate[bot] &lt;29139614+renovate[bot]@users.noreply.github.com&gt;

* Refresh reference assets for toolhive v0.27.2

* Document baselineClientScopes for embedded auth server

* Polish baselineClientScopes editorial pass

* Fix baselineClientScopes validation description

Clarify that when scopesSupported is omitted, the embedded auth server
validates baselineClientScopes against its default scope set
(openid, profile, email, offline_access) rather than failing to start.

This behavior shipped in toolhive v0.27.2 as part of #5233.

---------

Signed-off-by: renovate[bot] &lt;29139614+renovate[bot]@users.noreply.github.com&gt;
Co-authored-by: renovate[bot] &lt;29139614+renovate[bot]@users.noreply.github.com&gt;
Co-authored-by: github-actions[bot] &lt;github-actions[bot]@users.noreply.github.com&gt;
Co-authored-by: claude[bot] &lt;41898282+claude[bot]@users.noreply.github.com&gt;
Co-authored-by: Jakub Hrozek &lt;jakub@stacklok.com&gt;
diff --git a/.github/upstream-projects.yaml b/.github/upstream-projects.yaml
@@ -35,7 +35,7 @@ projects:
 
   - id: toolhive
     repo: stacklok/toolhive
-    version: v0.27.1
+    version: v0.27.2
     # 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/,
diff --git a/docs/toolhive/concepts/embedded-auth-server.mdx b/docs/toolhive/concepts/embedded-auth-server.mdx
@@ -145,6 +145,27 @@ the OAuth flow.
 - **Configurable token lifespans:** Access tokens, refresh tokens, and
   authorization codes have configurable durations with sensible defaults.
 
+## Baseline scopes for DCR clients
+
+Some MCP clients (for example, Claude Code) register via DCR with a narrowed
+`scope` value, then request a wider set of scopes at `/oauth/authorize`. By
+default, the embedded authorization server rejects those requests with
+`invalid_scope` because the registered client's scope set does not include the
+scopes being requested.
+
+To support this pattern, configure `baselineClientScopes` on the embedded auth
+server. The server merges these scopes into every DCR-registered client's scope
+set, so clients can request them at `/oauth/authorize` regardless of what they
+originally registered with. If `scopesSupported` is set explicitly on the
+embedded auth server, all baseline values must appear in it; if
+`scopesSupported` is omitted, the server validates against its default scope set
+(`openid`, `profile`, `email`, `offline_access`).
+
+Keep the baseline narrow (typically `openid` and `offline_access`). Every
+DCR-registered client gains the ability to request these scopes, including
+public clients like Claude Code, Cursor, and VS Code, so privileged scopes do
+not belong in the baseline.
+
 ## Session storage
 
 By default, session storage is in-memory. Upstream tokens are lost when pods
diff --git a/docs/toolhive/guides-k8s/auth-k8s.mdx b/docs/toolhive/guides-k8s/auth-k8s.mdx
@@ -544,13 +544,14 @@ kubectl apply -f embedded-auth-config.yaml
 
 **Configuration reference:**
 
-| Field                  | Description                                                                                                                                                                   |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `issuer`               | HTTPS URL identifying this authorization server. Appears in the `iss` claim of issued JWTs.                                                                                   |
-| `signingKeySecretRefs` | References to Secrets containing JWT signing keys. First key is active; additional keys support rotation.                                                                     |
-| `hmacSecretRefs`       | References to Secrets with symmetric keys for signing authorization codes and refresh tokens.                                                                                 |
-| `tokenLifespans`       | Configurable durations for access tokens (default: 1h), refresh tokens (default: 168h), and auth codes (default: 10m).                                                        |
-| `upstreamProviders`    | Configuration for upstream identity providers. MCPServer and MCPRemoteProxy support one provider; VirtualMCPServer supports multiple providers for sequential authentication. |
+| Field                  | Description                                                                                                                                                                                                                                                                                                               |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `issuer`               | HTTPS URL identifying this authorization server. Appears in the `iss` claim of issued JWTs.                                                                                                                                                                                                                               |
+| `signingKeySecretRefs` | References to Secrets containing JWT signing keys. First key is active; additional keys support rotation.                                                                                                                                                                                                                 |
+| `hmacSecretRefs`       | References to Secrets with symmetric keys for signing authorization codes and refresh tokens.                                                                                                                                                                                                                             |
+| `tokenLifespans`       | Configurable durations for access tokens (default: 1h), refresh tokens (default: 168h), and auth codes (default: 10m).                                                                                                                                                                                                    |
+| `upstreamProviders`    | Configuration for upstream identity providers. MCPServer and MCPRemoteProxy support one provider; VirtualMCPServer supports multiple providers for sequential authentication.                                                                                                                                             |
+| `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 [Baseline scopes for DCR clients](../concepts/embedded-auth-server.mdx#baseline-scopes-for-dcr-clients). |
 
 **Step 5: Create the MCPOIDCConfig and MCPServer resources**
 
diff --git a/docs/toolhive/guides-vmcp/authentication.mdx b/docs/toolhive/guides-vmcp/authentication.mdx
@@ -451,6 +451,25 @@ spec:
     authorizationEndpointBaseUrl: https://auth.example.com
 ```
 
+If your MCP clients register via DCR with a narrowed `scope` value and then
+request additional scopes at `/oauth/authorize` (a pattern used by Claude Code,
+among others), set `baselineClientScopes` so the embedded auth server merges
+those scopes into every registered client's scope set. If `scopesSupported` is
+set explicitly, all baseline values must appear in it; otherwise the server
+validates against its default scope set (`openid`, `profile`, `email`,
+`offline_access`). See
+[Baseline scopes for DCR clients](../concepts/embedded-auth-server.mdx#baseline-scopes-for-dcr-clients)
+for guidance on which scopes to include.
+
+```yaml
+spec:
+  authServerConfig:
+    issuer: https://auth.example.com
+    baselineClientScopes:
+      - openid
+      - offline_access
+```
+
 Each upstream provider `name` must be a valid DNS label (lowercase alphanumeric
 and hyphens, max 63 characters). This name is what
 [upstream token injection](#upstream-token-injection) and
diff --git a/static/api-specs/crds/mcpexternalauthconfigs.schema.json b/static/api-specs/crds/mcpexternalauthconfigs.schema.json
@@ -132,6 +132,17 @@
               "pattern": "^https?://[^\\s?#]+[^/\\s?#]$",
               "type": "string"
             },
+            "baselineClientScopes": {
+              "description": "BaselineClientScopes is a baseline set of OAuth 2.0 scopes guaranteed to be\nincluded in every client registration. The embedded auth server unions these\nscopes into the registered set returned by RFC 7591 Dynamic Client\nRegistration, so a client that narrows the `scope` field at /oauth/register\ncan still request the baseline scopes at /oauth/authorize. All values must\nbe present in the upstream-derived scopesSupported set; the auth server\nfails to start if any value is missing.\n\nSecurity: every client registered via /oauth/register will gain the\nability to request these scopes at /oauth/authorize, regardless of what\nthe client itself requested. Keep the baseline narrow (typically\n\"openid\" and \"offline_access\"). Adding a privileged scope here — e.g.\n\"admin:read\" — would grant it to every DCR-registered client, including\npublic clients like Claude Code, Cursor, and VS Code.",
+              "items": {
+                "minLength": 1,
+                "pattern": "^[\\x21\\x23-\\x5B\\x5D-\\x7E]+$",
+                "type": "string"
+              },
+              "maxItems": 10,
+              "type": "array",
+              "x-kubernetes-list-type": "atomic"
+            },
             "hmacSecretRefs": {
               "description": "HMACSecretRefs references Kubernetes Secrets containing symmetric secrets for signing\nauthorization codes and refresh tokens (opaque tokens).\nCurrent secret must be at least 32 bytes and cryptographically random.\nSupports secret rotation via multiple entries (first is current, rest are for verification).\nIf not specified, an ephemeral secret will be auto-generated (development only -\nauth codes and refresh tokens will be invalid after restart).",
               "items": {
diff --git a/static/api-specs/crds/virtualmcpservers.schema.json b/static/api-specs/crds/virtualmcpservers.schema.json
@@ -23,6 +23,17 @@
               "pattern": "^https?://[^\\s?#]+[^/\\s?#]$",
               "type": "string"
             },
+            "baselineClientScopes": {
+              "description": "BaselineClientScopes is a baseline set of OAuth 2.0 scopes guaranteed to be\nincluded in every client registration. The embedded auth server unions these\nscopes into the registered set returned by RFC 7591 Dynamic Client\nRegistration, so a client that narrows the `scope` field at /oauth/register\ncan still request the baseline scopes at /oauth/authorize. All values must\nbe present in the upstream-derived scopesSupported set; the auth server\nfails to start if any value is missing.\n\nSecurity: every client registered via /oauth/register will gain the\nability to request these scopes at /oauth/authorize, regardless of what\nthe client itself requested. Keep the baseline narrow (typically\n\"openid\" and \"offline_access\"). Adding a privileged scope here — e.g.\n\"admin:read\" — would grant it to every DCR-registered client, including\npublic clients like Claude Code, Cursor, and VS Code.",
+              "items": {
+                "minLength": 1,
+                "pattern": "^[\\x21\\x23-\\x5B\\x5D-\\x7E]+$",
+                "type": "string"
+              },
+              "maxItems": 10,
+              "type": "array",
+              "x-kubernetes-list-type": "atomic"
+            },
             "hmacSecretRefs": {
               "description": "HMACSecretRefs references Kubernetes Secrets containing symmetric secrets for signing\nauthorization codes and refresh tokens (opaque tokens).\nCurrent secret must be at least 32 bytes and cryptographically random.\nSupports secret rotation via multiple entries (first is current, rest are for verification).\nIf not specified, an ephemeral secret will be auto-generated (development only -\nauth codes and refresh tokens will be invalid after restart).",
               "items": {
diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml
@@ -355,44 +355,6 @@ components:
         use_pkce:
           type: boolean
       type: object
-    github_com_stacklok_toolhive_pkg_auth_tokenexchange.Config:
-      description: TokenExchangeConfig contains token exchange configuration for external
-        authentication
-      properties:
-        audience:
-          description: Audience is the target audience for the exchanged token
-          type: string
-        client_id:
-          description: ClientID is the OAuth 2.0 client identifier
-          type: string
-        client_secret:
-          description: ClientSecret is the OAuth 2.0 client secret
-          type: string
-        external_token_header_name:
-          description: ExternalTokenHeaderName is the name of the custom header to
-            use when HeaderStrategy is "custom"
-          type: string
-        header_strategy:
-          description: |-
-            HeaderStrategy determines how to inject the token
-            Valid values: HeaderStrategyReplace (default), HeaderStrategyCustom
-          type: string
-        scopes:
-          description: Scopes is the list of scopes to request for the exchanged token
-          items:
-            type: string
-          type: array
-          uniqueItems: false
-        subject_token_type:
-          description: |-
-            SubjectTokenType specifies the type of the subject token being exchanged.
-            Common values: oauthproto.TokenTypeAccessToken (default), oauthproto.TokenTypeIDToken, oauthproto.TokenTypeJWT.
-            If empty, defaults to oauthproto.TokenTypeAccessToken.
-          type: string
-        token_url:
-          description: TokenURL is the OAuth 2.0 token endpoint URL
-          type: string
-      type: object
     github_com_stacklok_toolhive_pkg_auth_upstreamswap.Config:
       description: |-
         UpstreamSwapConfig contains configuration for upstream token swap middleware.
@@ -604,6 +566,20 @@ components:
             `{authorization_endpoint_base_url}/oauth/authorize` instead of `{issuer}/oauth/authorize`.
             All other endpoints remain derived from the issuer.
           type: string
+        baseline_client_scopes:
+          description: |-
+            BaselineClientScopes is a baseline set of OAuth 2.0 scopes unioned into every
+            DCR registration. All values must appear in ScopesSupported; the auth server
+            rejects this RunConfig at startup otherwise. Empty means current behavior is
+            preserved (registered scope = client-requested, or DefaultScopes if empty).
+            When ScopesSupported is empty, the subset check uses registration.DefaultScopes
+            (the same set applyDefaults would substitute at startup) — so
+            BaselineClientScopes containing standard OIDC scopes works without enumerating
+            ScopesSupported explicitly.
+          items:
+            type: string
+          type: array
+          uniqueItems: false
         hmac_secret_files:
           description: |-
             HMACSecretFiles contains file paths to HMAC secrets for signing authorization codes
@@ -1143,6 +1119,44 @@ components:
           description: Whether to print resolved overlay paths for debugging
           type: boolean
       type: object
+    github_com_stacklok_toolhive_pkg_oauthproto_tokenexchange.Config:
+      description: TokenExchangeConfig contains token exchange configuration for external
+        authentication
+      properties:
+        audience:
+          description: Audience is the target audience for the exchanged token
+          type: string
+        client_id:
+          description: ClientID is the OAuth 2.0 client identifier
+          type: string
+        client_secret:
+          description: ClientSecret is the OAuth 2.0 client secret
+          type: string
+        external_token_header_name:
+          description: ExternalTokenHeaderName is the name of the custom header to
+            use when HeaderStrategy is "custom"
+          type: string
+        header_strategy:
+          description: |-
+            HeaderStrategy determines how to inject the token
+            Valid values: HeaderStrategyReplace (default), HeaderStrategyCustom
+          type: string
+        scopes:
+          description: Scopes is the list of scopes to request for the exchanged token
+          items:
+            type: string
+          type: array
+          uniqueItems: false
+        subject_token_type:
+          description: |-
+            SubjectTokenType specifies the type of the subject token being exchanged.
+            Common values: oauthproto.TokenTypeAccessToken (default), oauthproto.TokenTypeIDToken, oauthproto.TokenTypeJWT.
+            If empty, defaults to oauthproto.TokenTypeAccessToken.
+          type: string
+        token_url:
+          description: TokenURL is the OAuth 2.0 token endpoint URL
+          type: string
+      type: object
     github_com_stacklok_toolhive_pkg_registry.OAuthPublicConfig:
       description: |-
         AuthConfig contains the non-secret OAuth configuration when auth is configured.
@@ -1379,7 +1393,7 @@ components:
             ThvCABundle is the path to the CA certificate bundle for ToolHive HTTP operations
           type: string
         token_exchange_config:
-          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_auth_tokenexchange.Config'
+          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_oauthproto_tokenexchange.Config'
         tools_filter:
           description: |-
             DEPRECATED: Middleware configuration.
