Configuration
Authentication
Built-in sign-in with Admin, Editor and Viewer roles: first boot, sessions, Helm values, recovering a lost admin password, and what changes on KubeBolt Cloud.
On this page
Overview
KubeBolt ships with a built-in auth system and three roles: Admin, Editor and Viewer. Auth is on by default and keeps users in an embedded BoltDB file, so there is no external database or identity provider to run. A session is a short-lived JWT access token plus a rotating refresh token in an httpOnly cookie.
The open-source edition signs in with local usernames and passwords only — there is no OIDC, OAuth or SSO login, and every user belongs to one default team. Social sign-in, organizations and teams that own clusters are part of KubeBolt Cloud. For scripts, CI and MCP hosts, use API tokens instead of a user session.
First boot: KubeBolt creates a user named admin the first time it
starts. Unless you supplied the password (KUBEBOLT_ADMIN_PASSWORD or the
chart’s auth.adminPassword), it generates one, prints it once to the API
log and, when it runs in-cluster, stores it in the Secret
kubebolt-admin-password (keys username and password) in its own
namespace. An existing Secret of that name is never overwritten. The
first-login Setup Wizard
offers to change the password; if you missed both copies, see
Forgotten admin password.
kubectl -n kubebolt get secret kubebolt-admin-password \
-o jsonpath='{.data.password}' | base64 -d
Roles
KubeBolt enforces three roles with increasing levels of access. The API checks the role on every request; the UI only hides what you cannot use.
| Action | Viewer | Editor | Admin |
|---|---|---|---|
| View resources, YAML, describe, events, metrics, topology, insights, security findings | Yes | Yes | Yes |
| View pod logs | Yes | Yes | Yes |
| Chat with Kobi Copilot | Yes | Yes | Yes |
| Switch clusters | Yes | Yes | Yes |
| Execute a Kobi proposal | No | Yes | Yes |
| Pod terminal (exec) and ephemeral debug containers | No | Yes | Yes |
| Browse and download pod files (audited) | No | Yes | Yes |
| Edit YAML, create resources from a manifest | No | Yes | Yes |
| Restart, scale, roll back, set image / resources / env, cordon, evict | No | Yes | Yes |
| Reveal a Secret value | No | Yes (Admin in production namespaces) | Yes |
| Mute an insight | No | Yes | Yes |
| Port forwarding | No | Yes | Yes |
| Delete resources | No | No | Yes |
| Drain a node | No | No | Yes |
| Add / rename / delete clusters | No | No | Yes |
| Install, configure or remove integrations | No | No | Yes |
| Manage users, API tokens and agent tokens | No | No | Yes |
| Change settings (auth, AI, notifications, insight rules) | No | No | Yes |
| Read the audit trail and Kobi usage analytics | No | No | Yes |
A Viewer never reaches secret material: the views a Viewer can open hide it
the way the YAML view does. Since 2.6.4 that covers the Helm release view (its
values and rendered manifest), describe, an Argo CD Application’s Helm values,
parameters and plugin environment, and runtime events; the pod file browser
runs commands in the container, so it needs Editor, like the terminal.
Revealing a value takes Editor, a written reason and an audit record.
See Actions & Governance for the full action list and the role each one needs, and the REST API reference for the role behind every route.
Two things the role does not do:
- It does not change what KubeBolt may do in the cluster. Every action runs with KubeBolt’s own Kubernetes credentials — its ServiceAccount, the kubeconfig context, or the agent — never as the signed-in user. An action needs a role that allows it and cluster permissions that allow it; see RBAC & Permissions.
- It is read from the access token. A role change or a deleted user takes effect when that user’s access token is next refreshed — within the access-token lifetime (15 minutes by default). Resetting a user’s password from Administration → Access → Users ends their sessions at the next refresh too.
The last Admin cannot be demoted or deleted, and nobody can delete their own account.
Session Management
POST /api/v1/auth/loginreturns a JWT access token in the JSON body (accessToken). The UI keeps it in memory (never in localStorage) and sends it asAuthorization: Bearer.- The refresh token lives in the
kb_refreshcookie — httpOnly,SameSite=Strict, scoped to/api/v1/auth, andSecurewhen the request arrived over HTTPS. It is stored hashed server-side and rotates on every refresh. - Lifetimes:
KUBEBOLT_JWT_EXPIRY(access, default15m) andKUBEBOLT_JWT_REFRESH_EXPIRY(refresh, default168h, 7 days). Both are also editable at Administration → Access → Authentication; a change there applies after an API restart, which the page flags. - Every authenticated request validates the access token in middleware.
- Logout deletes the refresh token server-side and clears the cookie.
- Changing your own password (Change password in the account menu) revokes every other session’s refresh token and keeps the current one.
- Sign-in is throttled per username: five quick attempts, then one every
15 seconds. Excess attempts get
429with aRetry-Afterheader.
The login form takes a username — or an email, when the account has one. Scripts can sign in the same way, but an API token is the better fit: it does not expire every 15 minutes and carries its own scopes.
curl -s -X POST https://kubebolt.example.com/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"…"}' | jq -r .accessToken
Storage
Users, refresh tokens, API and agent tokens, UI-saved settings, Kobi
conversations, insight history and security findings all live in one BoltDB
file, kubebolt.db, under KUBEBOLT_DATA_DIR (default ./data). The Helm
chart sets /data and mounts a PersistentVolumeClaim (<release>-data,
auth.persistence, 1Gi ReadWriteOnce by default); the single-container
image keeps it in its /data volume.
BoltDB is single-writer, so run one API replica. The chart defaults to
replicaCount: 1 and uses the Recreate strategy, so an upgrade never starts
a new pod while the old one still holds the lock.
Environment Variables
| Variable | Default | Description |
|---|---|---|
KUBEBOLT_AUTH_ENABLED | true | Set to false to allow anonymous access — see Disabling Authentication. |
KUBEBOLT_ADMIN_PASSWORD | auto-generated | Password for the admin user, used only when that user is first created. When set, nothing is printed and no Secret is written. |
KUBEBOLT_JWT_SECRET | auto-generated | Key that signs access tokens. Must be at least 32 bytes; a shorter value stops the API at boot. When unset, a random key is generated and persisted in BoltDB. |
KUBEBOLT_JWT_EXPIRY | 15m | Access-token lifetime (Go duration). |
KUBEBOLT_JWT_REFRESH_EXPIRY | 168h | Refresh-token lifetime. |
KUBEBOLT_DATA_DIR | ./data | Directory for kubebolt.db. The chart and the images set /data. |
KUBEBOLT_RESET_ADMIN_PASSWORD | unset | Recovery hatch: when set, the API resets the admin password to this value at startup and then boots normally. The chart sets it from auth.resetAdminPassword. Clear it once you have logged in. |
The JWT secret also derives the key that encrypts secrets saved from the UI (AI provider keys, webhook URLs). Changing it signs everyone out and leaves those values unreadable — enter them again afterwards. The full variable list is in Environment variables.
Helm Configuration
When deploying via Helm, configure auth through values:
# values.yaml
auth:
enabled: true
adminPassword: "my-secure-password" # first boot only; generated if empty
jwtSecret: "" # generated and persisted if empty
existingSecret: "" # see below
resetAdminPassword: "" # recovery only
persistence:
enabled: true
size: 1Gi
storageClass: ""
To keep credentials out of your values file, point auth.existingSecret at a
Secret you manage. It may carry admin-password, jwt-secret, or both; a key
that is missing falls back to the generated default.
kubectl -n kubebolt create secret generic kubebolt-auth-secret \
--from-literal=admin-password='my-secure-password' \
--from-literal=jwt-secret="$(openssl rand -hex 32)"
helm install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
-n kubebolt --create-namespace \
--set auth.existingSecret=kubebolt-auth-secret
Or inline, for a quick test:
helm install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
-n kubebolt --create-namespace \
--set auth.adminPassword="my-secure-password"
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 set a new
password on the user named admin, and the new password needs at least
8 characters.
Path A — helm upgrade. Sets KUBEBOLT_RESET_ADMIN_PASSWORD on the
deployment; the API resets the password at next pod start, logs it, 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 \
-n kubebolt --reset-then-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 \
-n kubebolt --reset-then-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. The names
below assume the release is called kubebolt (deployment kubebolt-api, PVC
kubebolt-data):
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. With Docker Compose,
stop the api service and run the flag in a one-off container:
docker compose stop api
docker compose run --rm api --reset-admin-password=NEWPASS
docker compose start api
Disabling Authentication
To run KubeBolt without authentication (e.g., behind a VPN or for local development):
# Local development (from apps/api)
KUBEBOLT_AUTH_ENABLED=false go run ./cmd/server --kubeconfig ~/.kube/config
# Docker Compose (set in your shell or deploy/.env)
KUBEBOLT_AUTH_ENABLED=false
# Helm
helm install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
--set auth.enabled=false
With auth off, every request is treated as Admin, and the BoltDB store is
not opened at all. That turns off everything that lives in it: users, API and
agent tokens, settings saved from the UI (the Administration settings return
503), Kobi conversation history, insight episode history, and persisted
security findings and runtime events.
Warning: Disabling auth exposes full cluster management capabilities to anyone who can reach the KubeBolt UI. Only disable auth when access is already restricted at the network level.
On KubeBolt Cloud
KubeBolt Cloud runs the same roles and session model, with the pieces a multi-organization service needs:
- Sign-in. Email and password, or Continue with Google, Microsoft or
GitHub. Your organization has no
adminbootstrap user and no Helm recovery: a forgotten password is reset from Forgot password? on the sign-in page (the emailed link is valid for one hour). - Email verification. Until your email is verified, Kobi chat, inviting
users, creating teams and issuing API or agent tokens answer
403with"code": "email_unverified". - Organizations. Each signup creates an organization, and its first user is its Admin. Admins invite teammates by email (the invite link is valid for seven days) and pick each one’s organization role.
- Teams own clusters. An Admin assigns each cluster to a team from the Clusters page (Assign team). Admins see every cluster in the organization; Editors and Viewers see the clusters owned by their teams. A cluster not yet assigned to a team is visible to Admins only.
- Install-wide settings stay with us. Sign-in policy, token lifetimes and
the agent ingest channel are run by KubeBolt, not by an organization’s Admin.
Service tokens (
kbs_) are not issued to organizations; API keys (kbk_) are — see API tokens.