Every path into KubeHero is authenticated. We don't ship an identity store of our own — we proxy to whatever your organization already runs.

Self-hosted: Dex

Dex is the canonical OIDC proxy in the CNCF ecosystem. It connects to Okta, Azure AD, Google Workspace, GitHub, GitLab, or any LDAP.

Install

./infra/demo/stack-install.sh   # interactive, prompts for Dex
# or
helm install dex dex/dex \
  --namespace dex --create-namespace \
  --values dex-values.yaml

Configure for Okta

# dex-values.yaml
config:
  issuer: https://auth.acme.internal/dex
  storage:
    type: kubernetes
    config: { inCluster: true }
  connectors:
    - type: oidc
      id: okta
      name: Okta
      config:
        issuer: https://acme.okta.com
        clientID: 0oa4...
        clientSecret: "$OKTA_CLIENT_SECRET"
        scopes: [openid, email, profile, groups]

Wire KubeHero to Dex

# kubehero values.yaml
auth:
  dex:
    embedded: false   # installed separately above
    issuerURL: "https://auth.acme.internal/dex"

The dashboard now redirects unauthenticated users through Dex → Okta → back. The CLI uses device-flow or static client credentials.

Cloud / SaaS: WorkOS

Used when KubeHero Cloud hosts the control plane. WorkOS provides SSO + SCIM for enterprise tenants.

auth:
  workos:
    enabled: true
    apiKeySecret: "workos-api-key"       # via external-secrets
    clientIdSecret: "workos-client-id"

SCIM endpoint: https://api.kubehero.io/scim/v2/.... Paste that into your IdP's SCIM provisioning config. WorkOS handles deprovisioning, group sync, and just-in-time provisioning.

RBAC

Three built-in roles (Enterprise tier extends):

Role	Dashboard	CLI
Admin	Read + write everywhere, arm policies	Full
Operator	Read + arm policies in scoped clusters	Arm / undo within scope
Viewer	Read-only	Read-only

RBAC binds via OIDC group claims. In values.yaml:

auth:
  rbac:
    mapping:
      admin:    ["acme-sre-admins"]
      operator: ["acme-sre-oncall", "acme-platform"]
      viewer:   ["acme-engineering"]

Custom scopes per cluster / namespace are Enterprise-only.

Audit

Every authenticated action writes an audit_log row: actor.sub, actor.email, actor.groups, action, target, result, request_id. SIEM export via:

kubehero audit forward --syslog udp://siem.internal:514
kubehero audit forward --webhook https://siem.internal/hooks/kubehero
kubehero audit forward --s3 s3://acme-compliance/kubehero/

All three outputs include an HMAC signature so your SIEM can verify authenticity.

Token lifetimes

Dashboard session — 8 hours (sliding, refreshes on activity)
CLI token — 30 days, rotatable via kubehero auth rotate
Agent mTLS cert — 7 days, cert-manager rotates automatically

Service-to-service auth

Intra-platform RPCs use mTLS via cert-manager's CA. The agent holds a per-cluster cert issued at helm install time via kubehero cluster add. Inbound control-plane calls verify the cert's common name matches a registered cluster.

Identity · SSO · RBAC