Skip to content
Diverge

Web Dashboard & OIDC SSO

diverge-server includes an embedded single-page Web Dashboard (web/) built with React and ConnectRPC that visualizes active PreviewGroups, child Environments, autonomous AgentTask sandboxes, database migration hooks, live pod logs, and service topology graphs.

1. Enabling the Web Dashboard

Section titled “1. Enabling the Web Dashboard”

Enable both server.enabled and server.dashboard.enabled in your Helm values:

values-production.yaml
server:
  enabled: true
  replicaCount: 2
  dashboard:
    enabled: true
  cors:
    allowedOrigins: "https://diverge.example.com"

Install or upgrade the release from the root of your diverge repository checkout:

Terminal window
# Run from the root of the diverge repository checkout
kubectl apply -f charts/diverge/crds/
helm upgrade --install diverge charts/diverge \
  -n diverge-system --create-namespace \
  -f values-production.yaml

2. Authentication Modes

Section titled “2. Authentication Modes”

diverge-server supports a composable authentication chain:

  1. OIDC Browser Login + JWT Bearer Auth (--oidc-issuer-url) — For human users via Okta, Google Workspace, GitHub/Dex, Zitadel, or Keycloak.
  2. Kubernetes TokenReview Auth (always enabled) — For CI runners and kubectl ServiceAccount tokens.
  3. Macaroon Capability Auth (DIVERGE_MACAROON_ROOT_KEY) — For sandboxed AgentTask pods calling back into diverge-server (/mcp and /api/v1/agenttask/meter).

3. Configuring OIDC (Okta / Google / Dex / Keycloak)

Section titled “3. Configuring OIDC (Okta / Google / Dex / Keycloak)”
  1. Create a Secret for your OIDC client secret:
Terminal window
kubectl create secret generic diverge-oidc-client \
  -n diverge-system \
  --from-literal=client-secret="YOUR_OIDC_CLIENT_SECRET"
  1. Configure server.auth in Helm (matching charts/diverge/values.yaml):
server:
  enabled: true
  dashboard:
    enabled: true
  cors:
    allowedOrigins: "https://diverge.example.com"
  auth:
    audiences:
      - diverge-api
    secureCookies: true
    oidc:
      enabled: true
      issuerUrl: https://sso.example.com/oauth2/default
      clientId: diverge-web
      redirectUrl: https://diverge.example.com/auth/callback
      allowedGroups: "platform-engineering,developers"
      clientSecretSecretRef:
        name: diverge-oidc-client
        key: client-secret

Security Highlights

Section titled “Security Highlights”
  • CSRF State + Sanitized Redirects: /auth/login generates a cryptographic random state stored in an HttpOnly, SameSite=Lax cookie and sanitizes return_url to prevent open redirects.
  • Group Enforcement: When allowedGroups is configured, /auth/callback verifies group membership before issuing the diverge_token session cookie.
  • Namespace-Scoped Authorization: Human and ServiceAccount principals are checked with Kubernetes RBAC / SubjectAccessReview; Macaroon callers are checked against their caveats.

4. Interactive Dashboard Features

Section titled “4. Interactive Dashboard Features”
  • Environment Detail & Live Feature Flag Overrides (FlagsTab):
    • Add, toggle (true / false), or remove feature flag overrides (spec.features.overrides) directly from the Flags tab using partial UpdateMask (spec.features.overrides) updates, alongside one-click TTL extension and hook job retries.
  • Multi-Service PreviewGroup Detail:
    • Inspect Overview (source branch/PR, copyable routing headers, TTL countdown, and child service status table with direct links to each child Environment), interactive Topology graph, Kubernetes Conditions, and live YAML.
  • Autonomous AgentTask Steering & Linked Previews:
    • Send live steering guidance, pause/resume execution with optional USD budget bumps, stream sandbox pod logs, and jump directly to the task’s Linked Preview Environment (agent-preview-<task>) and external preview URL.