[Gap]: Configure the Connector Gateway: remaining gaps and inaccuracies at chart v0.18.0

Summary

I followed Configure the Connector Gateway (docs/platform/enterprise-platform/configure-connector-gateway.mdx) to enable the gateway on a GitOps (Flux) install of the Stacklok Enterprise Platform chart v0.18.0. I compared the result against a known-working reference cluster. Most of the page held up, but I found the gaps and inaccuracies below.

Unless noted otherwise, I checked each one by running helm template on the v0.18.0 chart source or by reading the chart and binary source at v0.18.0. I haven't run any of them on a live cluster.

Related: #1159, which covers the overall deployment contract. This issue lists specific problems with the page as it stands now.

Inaccuracies

1. global.redis does not configure the gateway's Redis at chart v0.18.0

The Prerequisites section, and the global.redis table in deployment.mdx, say that the gateway inherits the host, port, and password Secret from global.redis. At v0.18.0 the connector-gateway subchart templates never read global.redis.

I rendered the page's example values (global.redis.host, port, existingSecret) and set nothing under connector-gateway.enterpriseConfig.redis. The gateway's enterprise.yaml came out with authServer.storage.type: redis and no Redis address or credentials, and the Deployment had no Redis env vars.

What worked was configuring the gateway's own connection:

connector-gateway:
  enterpriseConfig:
    authServer:
      storage:
        type: redis          # redis_config omitted -> defaults from enterpriseConfig.redis
    redis:
      addr: '<host>:6379'
      auth_type: aclUser
      key_prefix: 'thv:auth:'
      acl_user_config:
        username_env_var: REDIS_USERNAME
        password_env_var: REDIS_PASSWORD
  extraEnv:
    - name: REDIS_USERNAME
      value: cgw
    - name: REDIS_PASSWORD
      valueFrom: { secretKeyRef: { name: <secret>, key: <key> } }

The chart's values.yaml describes a reference least-privilege ACL for the cgw user, fenced to ~thv:auth:* and ~connector-gateway:*, plus related caveats. None of that appears in the docs. The docs should either show enterpriseConfig.redis or name the chart version where inheritance from global.redis starts working.

2. The uid guidance only fixes the Enterprise Manager side

The page says to add an enterprise-manager.directory.issuers entry with binding_claim: 'uid' when the IdP identifies users by a claim other than sub, such as Okta. That isn't enough for the gateway:

• The gateway's injected primary-idp upstream, and the directory.bindingClaims["primary-idp"] entry the chart derives from it, come from global.stacklok.primaryIdp.subjectClaim, which defaults to sub. A render without it produces subject_claim: sub and bindingClaims: {primary-idp: sub}. That conflicts with a directory issuer bound on uid, so users don't resolve.
• primaryIdp.subjectClaim isn't documented anywhere: not on this page, not in the "Corporate identity provider settings" table, and not in the umbrella values.yaml.
• The gateway reads the ID token. Okta puts uid on custom-authorization-server access tokens by default, but not on ID tokens. Okta users need to add a uid claim (value user.id) included in the ID token. The page should say so.

3. The control-plane validator is never configured

The caBundleRef warning and verification step 3 both refer to the "control-plane token validator, which checks the corporate tokens the console sends". The page never shows how to configure it. A render of the page's example has no controlPlane section at all.

In the v0.18.0 AppConfig source (internal/infra/vmcp/app_config.go), a nil controlPlane.incomingAuth.oidc makes the control plane reuse the data-plane validator, which only accepts tokens from the gateway's own authorization server. That means the console's corporate token, and the curl in step 3, wouldn't be accepted. The page needs:

connector-gateway:
  enterpriseConfig:
    controlPlane:
      incomingAuth:
        oidc:
          issuer: '<primaryIdp issuer>'    # must match the primary-idp upstream issuer_url
          audience: '<aud of the token the console sends>'
          jwksUrl: '<optional>'

The page should also cover the audience caveat from the source: use a gateway-scoped audience, and note that Okta access tokens may be opaque or carry api://default.

Gaps

4. Caller auth also gates the AI Gateway, and its instructions are understated

callerAuth applies to the whole gRPC port: both the cleartext :9091 listener and the TLS listener. On an install that also runs the AI Gateway, setting clusterOidcIssuer gates the api-key-service's ValidateKey call, which runs on every virtual-key request. The page covers this with one line ("keep its entries on saSubjectAllowlist"). That line implies the entries already exist, and it leaves out what's actually needed:

• the subject to add: system:serviceaccount:<ns>:<AIGateway CR name>-api-key-service;
• spec.virtualAPIKeys.directory.insecure: false on the AIGateway CR, so the api-key-service projects and presents its token. If this is missed, virtual keys fail with 503 "key store temporarily unavailable";
• enterprise-manager.grpc.insecure must be false, or not set. Installs that previously set true for plaintext in-cluster gRPC bypass the gate entirely.

The umbrella's apiKeyServiceCallerAuthGuard does catch a missing subject at render time, but the page should explain the change before readers hit that error.

5. vmcpConfig.groupRef appears to be required but is missing from the example

The v0.18.0 connector-gateway chart defaults vmcpConfig.groupRef: "", and the page's example doesn't set it. The vMCP config validator the gateway loads with rejects an empty group: toolhive pkg/vmcp/config/validator.go at the version pinned in enterprise/connector-gateway/go.mod (v0.49.0) returns "group reference is required". Every one of the chart's own ci/*-values.yaml files sets groupRef.

If that validator runs at startup, the documented example crash-loops. I set groupRef plus a matching empty MCPGroup rather than test that, so this needs confirming. Either way, the page should say whether groupRef is required, and whether the named MCPGroup must exist.

6. The fourth allowlist and the effects of name overrides

• The page lists three allowlists. A fourth, meteringSaSubjectAllowlist, is computed by the umbrella from <release>-connector-gateway. So is toolhive-cloud-ui.connectorGatewayUrl, the URL that turns on the console Connectors pages.
• With connector-gateway.fullnameOverride or nameOverride, the umbrella's drift guards (meteringAllowlistDriftGuard, connectorGatewayUrlDriftGuard) fail the render until both values are overridden by hand. The page mentions name overrides only when confirming Service names. It should list the values that must change together with an override.

7. Missing baseline_client_scopes for common MCP clients

MCP clients that register through DCR with openid and then request offline_access at /oauth/authorize (for example Claude Code, Cursor, and VS Code) are rejected with invalid_scope. The connection then stalls at "needs authentication". The working fix is:

enterpriseConfig:
  authServer:
    baseline_client_scopes: [openid, offline_access]

This is the toolhive auth server's baseline_client_scopes (#5233). I took this from the known-working configuration and didn't reproduce the failure, but it belongs in the example or in Troubleshooting.

8. Smaller items

• CA-only Secret under GitOps. "Copy ca.crt out of its Secret" is a one-off kubectl step that goes stale when cert-manager rotates the CA. Suggest a render-and-apply-safe pattern: a trust-manager Bundle, an External Secrets Kubernetes-provider copy, or an externally generated CA that backs a cert-manager ca Issuer.
• clusterOidcIssuer reachability. Say whether the Enterprise Manager fetches discovery and JWKS from the issuer URL (on EKS this is a public oidc.eks.*.amazonaws.com URL) or through the API server. This matters for restricted-egress and air-gapped clusters, where a blocked fetch would reject every gRPC caller.
• Existing directory NetworkPolicy. With directory.enabled, the Enterprise Manager chart already renders a <fullname>-directory NetworkPolicy. It admits api-key-service and connector-gateway pods on both gRPC ports. Mentioning it would show readers when directory.kek.externallyManagedNetworkPolicy: true is a reasonable choice compared with grpc.networkPolicy.enabled.
• Directory KEK Secret format. deployment.mdx shows kek.generate: true only. For the existingSecret path that this page recommends for GitOps, it should document the expected .data.kek format: a JSON version map, {"1": "<base64 of 32 bytes>"}. The gateway's own KEK uses a different format, 32 raw bytes.