Enable on the Cluster

One-time cluster setup an operator runs to enable the OAuth custom connector. After this, end users connect Claude Desktop, Codex, or the Gemini CLI using the client-specific pages — no more operator involvement.

In This Topic

Prerequisites

  • A running Kloudfuse cluster with an upstream SSO identity provider already wired into kfuse-auth (Okta, Azure AD, Google, or SAML).

  • Cluster access to run helm upgrade.

  • Your cluster URL is reachable over HTTPS from each end user’s machine (the AI client opens the login page in the user’s browser).

1. Enable the connector in custom_values.yaml

Pick one of two install layouts:

The Kloudfuse install deploys the kf-mcp Pod alongside everything else. One helm release, one set of values.

kf-mcp:
  enabled: true
yaml

Recommended for most installs.

Either way, sessions survive helm upgrade; to force a re-auth across all users, delete the kfuse-mcp-oauth-dcr-secret and kfuse-mcp-oauth-signing-key Secrets and re-run helm upgrade.

2. Set the connector base URL

The connector advertises its OAuth endpoints (the .well-known discovery documents, /authorize, /token, and /register) at a single public base URL. AI clients read that base URL during login, so it must be the https:// hostname the user’s browser can actually reach.

By default Kloudfuse derives the base URL automatically as https://<tls.host>;, using the tls.host value already in your custom_values.yaml. If tls.host is set to the hostname your users reach the cluster on, you do not need to configure anything else — skip to the next step.

If tls.host is not set in your custom_values.yaml, the derived base URL is empty and the connector advertises an invalid issuer — OAuth login then fails for every client. In that case you must set the base URL explicitly:

user-mgmt-service:
  config:
    MCPConnector:
      BaseURL: https://<MCP_CONNECTOR_HOST>
yaml

Replace <MCP_CONNECTOR_HOST> with the full hostname end users reach (for example kloudfuse.example.com). The same override is also required for split-hostname deployments, where the connector is served on a different host than the one in tls.host.

An explicit MCPConnector.BaseURL always takes precedence over the tls.host-derived value. Whichever value applies, that host must serve the OAuth routes (/.well-known/…​, /authorize, /token, /register, and /mcp) — confirm with the Verify step below.

3. (Optional) Customize the redirect URI allowlist

Each AI client registers itself dynamically via RFC 7591 (DCR) on first use, then asks the authorization server to redirect the browser back to a client-specific callback URL after SSO. user-mgmt-service rejects any redirect_uri that is not on its allowlist.

The chart ships with a default that covers the supported clients out of the box — Claude Desktop / web, Codex (app + CLI), and Gemini CLI:

user-mgmt-service:
  config:
    MCPConnector:
      AllowedRedirectURIs:
        - "http://localhost:*"                             # Codex / Gemini CLI (loopback)
        - "http://127.0.0.1:*"                             # Same, IPv4 literal
        - "https://claude.ai/api/mcp/auth_callback"        # Claude Desktop / Claude web
        - "https://claude.com/api/mcp/auth_callback"       # Same, .com TLD
yaml

You only need to override this list if you want a stricter allowlist (drop the loopback entries to lock out CLI clients, for example) or if you onboard a new MCP client whose callback URL is not in the default. Wildcard ports (*) on the loopback entries are required because the CLI clients bind a random ephemeral port for the OAuth callback.

To override, paste the same block into your custom_values.yaml with the entries you want — Helm replaces the list rather than merging.

If a user reports invalid_redirect_uri after a successful SSO sign-in, see Troubleshooting → invalid_redirect_uri after sign-in.

4. Apply the changes

Run the standard Kloudfuse upgrade command with your usual chart reference and custom_values.yaml. A representative form:

helm upgrade kfuse oci://us-east1-docker.pkg.dev/mvp-demo-301906/kfuse-helm/kfuse -f custom_values.yaml
bash

For cluster-specific chart paths, version flags, and pre-flight steps, see Upgrade Kloudfuse.

After the upgrade, wait for the kf-mcp Pod to reach Running, then restart user-mgmt-service so its Pod starts after kf-mcp. user-mgmt-service reads MCP connector state at startup and must come up second; if the user-mgmt-service Pod is older than the kf-mcp Pod, OAuth requests fail with a 401 until you restart it.

# Wait for kf-mcp
kubectl wait --for=condition=Ready pod -l app.kubernetes.io/name=kf-mcp -n <namespace> --timeout=180s

# Restart user-mgmt-service
kubectl rollout restart deploy/user-mgmt-service -n <namespace>

# Confirm ordering: user-mgmt-service AGE should now be lower than kf-mcp
kubectl get pods -n <namespace> -l 'app.kubernetes.io/name in (kf-mcp,user-mgmt-service)'
bash

Verify

From any machine that can reach your cluster URL:

curl https://<KLOUDFUSE_URL>/.well-known/oauth-protected-resource/mcp
bash

You should see a JSON document like:

{
  "resource": "https://<KLOUDFUSE_URL>/mcp",
  "authorization_servers": ["https://<KLOUDFUSE_URL>"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Kloudfuse MCP (OAuth)"
}
json

If this returns a 404 or an HTML page, the connector is not enabled yet — recheck the custom_values.yaml entries above.

Works on both Envoy Gateway and ingress-nginx clusters; no ingress-controller tweaks required.