Authentication

Overview

KubeBolt ships with a built-in auth system that supports three roles: Admin, Editor, and Viewer. Auth is enabled by default and uses BoltDB for user storage — no external database needed. Sessions use a short-lived JWT access token plus a refresh token in an httpOnly cookie.

Roles

KubeBolt enforces three roles with increasing levels of access:

See Actions & Governance for the full action list and the role each one needs.

Session Management

• On login the API returns a JWT access token, which the UI keeps in memory (never in localStorage) and sends as Authorization: Bearer
• The refresh token lives in the kb_refresh httpOnly, SameSite=Strict cookie, is stored hashed server-side and rotates on every refresh
• Expiry is configurable: KUBEBOLT_JWT_EXPIRY (access, default 15m) and KUBEBOLT_JWT_REFRESH_EXPIRY (refresh, default 168h, 7 days)
• Tokens are validated on every API request via auth middleware
• Logout invalidates the refresh token server-side and clears the cookie

Storage

User accounts are stored in a local BoltDB file. By default, the database is written to ./data/kubebolt.db. Use the KUBEBOLT_DATA_DIR environment variable to customize the storage path. In Kubernetes deployments, mount a PersistentVolume to this path for durability.

Environment Variables

Helm Configuration

When deploying via Helm, configure auth through values:

# values.yaml
auth:
  enabled: true
  adminPassword: "my-secure-password"

# Or use an existing Kubernetes secret
auth:
  enabled: true
  existingSecret: "kubebolt-auth-secret"
  # Secret must contain keys: admin-password, jwt-secret

# Install with inline password
helm install kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --set auth.adminPassword="my-secure-password"

# Install with existing secret
helm install kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --set auth.existingSecret=kubebolt-auth-secret

Forgotten admin password

The first-boot log line prints once and the first-boot Secret does not track later password changes, so KubeBolt ships two recovery paths. Both reset the admin user’s password hash and log the reset to the API log, so the action is auditable. Minimum length is 8 characters.

Path A — helm upgrade. Sets KUBEBOLT_RESET_ADMIN_PASSWORD on the deployment; the API resets the password at next pod start and then continues its normal boot. The chart’s strategy: Recreate guarantees the old pod is gone — and the BoltDB lock released — before the new one runs the reset.

helm upgrade kubebolt oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --reuse-values --set auth.resetAdminPassword=NEWPASS

# log in with NEWPASS, change to your real password from the Account menu, then
# clear the value so it doesn't sit in your release values:
helm upgrade kubebolt oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --reuse-values --set auth.resetAdminPassword=

Path B — a one-shot Job, for runbooks or installs not managed by Helm. BoltDB is single-writer, so the API has to be scaled to zero first:

NS=kubebolt   # your release namespace
IMAGE=$(kubectl -n $NS get deploy/kubebolt-api -o jsonpath='{.spec.template.spec.containers[0].image}')

kubectl -n $NS scale deploy/kubebolt-api --replicas=0
kubectl -n $NS apply -f - <<EOF
apiVersion: batch/v1
kind: Job
metadata: { name: kubebolt-pw-reset }
spec:
  ttlSecondsAfterFinished: 60
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: reset
        image: $IMAGE
        command: ["kubebolt-api", "--reset-admin-password=NEWPASS"]
        env: [{ name: KUBEBOLT_DATA_DIR, value: /data }]
        volumeMounts: [{ name: data, mountPath: /data }]
      volumes:
      - name: data
        persistentVolumeClaim: { claimName: kubebolt-data }
EOF
kubectl -n $NS wait --for=condition=Complete job/kubebolt-pw-reset --timeout=60s
kubectl -n $NS scale deploy/kubebolt-api --replicas=1

The same flag works on the single binary — kubebolt --reset-admin-password=NEWPASS resets the password and exits without starting a server.

Disabling Authentication

To run KubeBolt without authentication (e.g., behind a VPN or for local development):

# Local development
KUBEBOLT_AUTH_ENABLED=false go run cmd/server/main.go --kubeconfig ~/.kube/config

# Docker Compose (set in deploy/.env)
KUBEBOLT_AUTH_ENABLED=false

# Helm
helm install kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --set auth.enabled=false