Skip to navigation
ReferenceDeployment & Architecture

Configure Single Sign-On

View as Markdown

Kumo supports single sign-on through OIDC (OpenID Connect), allowing you to bring your own identity provider (IdP). This enables integrations with Okta, Azure Active Directory, and any other OIDC-compliant provider. Authentication is configured entirely in your Helm values and Kubernetes Secrets; no Kumo-managed auth proxy is involved.

This page describes how to register your OIDC client and supply the credentials to Kumo. For illustration, Okta is used as the OIDC provider, but the steps apply to any OIDC-compliant IdP.

Configure Okta

  1. Go to your Applications and create a new application with the following settings:

    • Sign-in method: OIDC - OpenID Connect
    • Application type: Web Application (confidential client - not Single-Page Application)

  2. Under General Settings, enable the Authorization Code grant type.

  3. Add the following sign-in redirect URI:

    • Sign In: https://<your-exposure-host>/v0/auth/callback

    Replace <your-exposure-host> with the public hostname configured in exposure.host in your Helm values.

  4. Ensure the token settings issue RS256 id_token values whose aud matches the client ID, and that the id_token includes sub and email claims. Request scopes openid email profile.

  5. Select your preferred Assignment policy and click Save.

  6. Copy the following values from the Okta application:

    • Client ID (example: 0oa654ok0jBdIJrpT5d7)
    • Client Secret
    • Issuer URL (example: https://dev-22499602.okta.com)

Create a Kubernetes Secret

Store the OIDC client secret in a Kubernetes Secret in the Helm release namespace before running helm install:

kubectl create secret generic kumo-oidc \
  --from-literal=client-secret='<oidc-client-secret>' \
  -n <namespace>

Configure Helm Values

Enable auth and supply the OIDC coordinates in your values.yaml:

exposure:
  host: <your-exposure-host>   # required when auth.enabled=true
auth:
  enabled: true
  method: oidc
  adminEmails:
    - first-admin@example.com  # bootstraps the first admin on initial login
  oidc:
    issuerUrl: "https://dev-22499602.okta.com"
    clientId: "0oa654ok0jBdIJrpT5d7"
    groupsClaim: groups         # id_token claim carrying the user's groups
    clientSecret:
      secretName: kumo-oidc
      secretKey: client-secret

auth.adminEmails bootstraps the first user to log in (while no admin exists yet) as an admin. After an admin exists, additional admins must be promoted through the PATCH /v0/admin/users/<user_id> API.

Group-to-permission mapping is configured at runtime through the Kumo admin UI or API; groupsClaim only tells Kumo which id_token claim to read.