Authentication

Kokumi’s web UI and API server require authentication. Two identity providers are supported and can be enabled independently:

Admin account: the built-in username/password login (default).
OIDC: single sign-on through any standards-compliant OpenID Connect provider (Dex, Keycloak, Okta, Google, Entra ID, …).

Logging in

The default admin credentials are:

Username	Password
`admin`	`admin`

Change the password before any non-development use. Generate a new bcrypt hash with htpasswd and patch the kokumi-server-auth Secret:

kubectl -n kokumi patch secret kokumi-server-auth \
  --type merge \
  -p "{\"stringData\":{\"password-hash\":\"$(htpasswd -nbB admin 'your-new-password' | cut -d: -f2)\"}}"

You can also change the username from the default admin by setting stringData.username in the same Secret.

The Secret must carry these keys:

Key	Purpose
`username`	Login name for the admin account (optional, overrides `spec.auth.adminUser.username`).
`password-hash`	bcrypt hash of the password.

Token signing key

All session tokens (admin and OIDC alike) are signed with a single HMAC key stored in the kokumi-server-tokens Secret under the signing-key key.

If the Secret does not exist, the Kitchen controller creates it with a generated random key. It is never rotated automatically.

If the Secret already exists, the controller uses it as-is and never modifies it:

kubectl -n kokumi create secret generic kokumi-server-tokens \
  --from-literal=signing-key="$(openssl rand -base64 32)"

To use a differently named Secret, set spec.auth.tokenSigningKeySecretRef:

spec:
  auth:
    tokenSigningKeySecretRef:
      name: my-gitops-managed-key

Configuring the admin user

The built-in admin account is configured through the singleton Kitchen resource (named default in the install namespace). The following fields are supported under spec.auth.adminUser:

Field	Type	Default	Description
`enabled`	`*bool`	`true`	Toggle the admin account. Set to `false` to disable UI login (e.g. once an external identity provider is wired up).
`username`	`string`	`admin`	Login username. Must not contain whitespace or `/`.
`secretRef`	`LocalObjectReference`	`kokumi-server-auth`	Name of the `Secret` holding the credentials (`username`, `password-hash`) in the same namespace.

When secretRef is omitted, the server uses the default Secret name kokumi-server-auth.

Example — custom username backed by a dedicated Secret:

apiVersion: delivery.kokumi.dev/v1alpha1
kind: Kitchen
metadata:
  name: default
  namespace: kokumi
spec:
  auth:
    adminUser:
      username: root
      secretRef:
        name: kokumi-admin-creds

The server watches the Secret and the Kitchen resource, so credential and configuration changes are picked up automatically; no restart is needed.

Disabling the admin account

Set enabled: false to turn off the built-in login. This is useful when an external identity provider takes over authentication.

apiVersion: delivery.kokumi.dev/v1alpha1
kind: Kitchen
metadata:
  name: default
  namespace: kokumi
spec:
  auth:
    adminUser:
      enabled: false

OIDC-only (no admin account)

You can run OIDC as the sole identity provider by omitting the adminUser block entirely. The login page then shows only the SSO button:

apiVersion: delivery.kokumi.dev/v1alpha1
kind: Kitchen
metadata:
  name: default
  namespace: kokumi
spec:
  auth:
    oidc:
      issuerURL: https://dex.example.com
      clientID: kokumi
      clientSecretRef:
        name: kokumi-server-oidc

No admin credentials Secret is needed in this mode; only the OIDC client secret and the token signing key (see above) are required.

OIDC single sign-on

Kokumi can delegate authentication to an OIDC provider. When OIDC is enabled, the login page shows a “Sign in with SSO” button that starts the standard authorization-code flow (with PKCE). After the provider authenticates the user, Kokumi mints its own short-lived session token, sp that upstream tokens are never stored on the server.

Authorization scope. OIDC in Kokumi is an authentication mechanism only. Any successfully authenticated user is granted full admin access. Fine-grained authorization (per-user roles/permissions) is currently not supported but will be added later.

Configuration

OIDC is configured under spec.auth.oidc on the singleton Kitchen resource:

Field	Type	Default	Description
`issuerURL`	`string`	(required)	OIDC issuer base URL (must be a valid `https://` or `http://` URL). Discovery is performed against `<issuerURL>/.well-known/openid-configuration`.
`clientID`	`string`	(required)	OAuth2 client identifier registered with the provider.
`clientSecretRef`	`*LocalObjectReference`	`kokumi-server-oidc`	Name of the `Secret` (in the install namespace) holding the client secret under the `client-secret` key.
`usernameClaim`	`string`	`email`	ID-token claim used as the Kokumi username. Supports dotted nested paths (e.g. `realm_access.preferred_username`). Must resolve to a string.
`scopes`	`[]string`	`["openid","profile","email"]`	OAuth2 scopes requested during the flow (max 16).

Create the client-secret Secret:

kubectl -n kokumi create secret generic kokumi-server-oidc \
  --from-literal=client-secret='your-oauth-client-secret'

Enable OIDC on the Kitchen:

apiVersion: delivery.kokumi.dev/v1alpha1
kind: Kitchen
metadata:
  name: default
  namespace: kokumi
spec:
  auth:
    oidc:
      issuerURL: https://dex.example.com
      clientID: kokumi
      clientSecretRef:
        name: kokumi-server-oidc
      usernameClaim: email

Last updated on September 15, 2026

Authorization