Authentication & IAM

Celum’s backend owns authentication (OIDC) and authorization (IAM). A user signs in through your identity provider, receives a signed session cookie, and every action is checked against IAM policies and recorded in the audit log.

Authentication

Modes

OIDC

Production. Sign-in delegated to your provider (Entra ID or any OIDC issuer).

AUTH_DISABLED

Development only. Injects a mock dev@localhost admin and skips all token validation.

The OIDC flow

The backend serves four auth endpoints:

Endpoint	Purpose
`GET /auth/login`	Generates a random `state`, sets a short-lived state cookie, redirects to the provider
`GET /auth/callback`	Validates `state`, exchanges the code, verifies the ID token, creates the session
`GET /auth/logout`	Clears the session cookie
`GET /auth/session`	Returns the current user (`authenticated`, `email`, `name`, `groups`, `iamEnabled`)

The ID token is verified (signature + expiry) and the user’s email, name, and groups are read from it. The groups claim drives IAM membership. On successful callback the backend issues an HS256-signed JWT stored in the k8s-gate-session cookie:

HttpOnly, Secure, SameSite=Lax
Claims: email, name, groups, issuer k8s-gate, plus issued/expiry times
Lifetime from SESSION_MAX_AGE (default 86400 = 24h)

Configuration

Variable	Notes
`OIDC_ISSUER`	Discovery URL. Auto-constructed from `AZURE_AD_TENANT_ID` if unset (`https://login.microsoftonline.com/{tenant}/v2.0`).
`OIDC_CLIENT_ID`	Falls back to `AZURE_AD_CLIENT_ID`.
`OIDC_CLIENT_SECRET`	Falls back to `AZURE_AD_CLIENT_SECRET`.
`OIDC_REDIRECT_URL`	Callback URL, e.g. `https://api.example.com/auth/callback`.
`OIDC_MAPPING_SOURCE`	Which claim maps to IAM groups: `groups` (default) or `roles`.
`OIDC_GROUPS_CLAIM`	Explicit claim-name override (takes precedence).
`SESSION_SECRET`	HMAC key for signing sessions. Set this — if unset a random key is generated at startup and sessions don’t survive a restart.
`SESSION_MAX_AGE`	Session lifetime in seconds (default `86400`).
`FRONTEND_URL`	Redirect target after login/logout.
`COOKIE_DOMAIN`	Cookie domain for cross-subdomain sessions (e.g. `.example.com`).

Authorization (IAM)

IAM is AWS-inspired: policies with Allow/Deny statements are attached to groups, groups map to your provider’s groups (or hold manual members), and every request is evaluated against the user’s effective policies. The mechanics — KRN matching, wildcard rules, unmapped routes, cache refresh — are covered in depth in Permissions model.

Enforcement

IAM_ENABLED defaults to audit-only. When false, denied requests are logged but still allowed. Set IAM_ENABLED=true to enforce — otherwise authorization is effectively off.

When enforcing, a denied request returns 403, and any route that isn’t mapped to a permission is denied by default.

KRN — resource names

Resources are addressed by KRN (krn:vks:...), built from type:id segments:

krn:vks:supervisor:<supervisor>
krn:vks:supervisor:<supervisor>:cluster:<cluster>
krn:vks:iam:*

Wildcards are supported: * matches one segment, a trailing * matches the rest, and prefixes like prod-* match prod-cluster-1.

Policy document

{
  "version": "2024-01-01",
  "statements": [
    {
      "sid": "allow-read",
      "effect": "Allow",
      "actions": ["cluster:List", "cluster:Get"],
      "resources": ["krn:vks:supervisor:*:cluster:*"]
    },
    {
      "effect": "Deny",
      "actions": ["cluster:Delete"],
      "resources": ["krn:vks:*"]
    }
  ]
}

Actions support exact (cluster:List), service (cluster:*), and full (*:*) wildcards. Every action Celum defines is listed in Permissions reference.

Evaluation order

Default deny

With no matching Allow, access is denied.

Explicit deny wins

Any matching Deny statement immediately denies, overriding any Allow.

Explicit allow

Otherwise, a matching Allow grants access.

Groups

A user’s groups come from two sources, combined:

Provider-mapped — a group whose oidc_group_id matches one of the user’s OIDC group/role claims (per OIDC_MAPPING_SOURCE).
Manual — emails added directly to a group.

The match on oidc_group_id is exact, against whichever claim OIDC_MAPPING_SOURCE / OIDC_GROUPS_CLAIM selects. With OIDC_MAPPING_SOURCE=groups that means the provider’s group object ID, not its display name; with roles it means the app role’s value.

Bootstrapping the first admin

A fresh database is seeded with an Administrators group holding the K8sGateAdmin policy and mapped to the OIDC claim value krn:vks:admin. Without that seed, turning on IAM_ENABLED against an empty database locks everyone out — there would be policies, but no group carrying them and no claim mapping to anything, so every request ends in the default deny. To get in, either assign the claim value krn:vks:admin to your account at the identity provider, or edit the Administrators group’s mapped OIDC group so it matches a claim you already carry.

Built-in policies

These are reconciled at startup and are read-only in the UI.

Policy	Grants
`K8sGateAdmin`	Full access (`:` on `krn:vks:*`)
`K8sGateOperator`	Read everything + manage clusters/helm/argocd/apps/VMs, limited deletes
`K8sGateViewer`	Read-only; no credential downloads
`K8sGateSensitiveRead`	Kubeconfig / talosconfig / SSH-password downloads

Credential downloads are deliberately not in Operator or Viewer. Attach K8sGateSensitiveRead separately to the people who should be able to pull a kubeconfig, talosconfig, or SSH password.

Managing IAM in the UI

Page	What you can do
`/iam/policies`	List, create, edit, delete custom policies (managed ones are read-only)
`/iam/groups`	Manage groups, their members, and attached policies; set the mapped OIDC group
`/iam/me`	View your effective permissions and manage API tokens

API clients can authenticate with a Bearer token issued from My permissions instead of the session cookie.

What commonly goes wrong

Symptom	Cause
`403 {"action":"unmapped"}`	The route carries no permission mapping. With IAM enabled, unmapped routes are denied outright — no policy can grant them.
A user’s new group has no effect for up to 30s	The policy cache refreshes on a 30-second loop.
The right policy is attached, still denied	A `Deny` statement matches. Explicit deny always wins, regardless of how broad the Allow is.
Everything works, yet nothing is enforced	`IAM_ENABLED` is not `true`. Denials are logged as `AUDIT-ONLY would-deny` and the request proceeds.

Next steps

Permissions model

How routes resolve to actions and KRNs, and how matching really works.

Permissions reference

Every action Celum defines, by service.

Architecture

Where session and IAM checks sit in the request pipeline.

Create a cluster

Cluster creation is gated by cluster:Create.

Get Started

Concepts

Clusters

GitOps & Apps

Virtual machines

Networking

Security

Platform Health

Storage

Reference

Authentication & IAM

Authentication

Modes

OIDC

AUTH_DISABLED

The OIDC flow

Configuration

Authorization (IAM)

Enforcement

KRN — resource names

Policy document

Evaluation order

Groups

Bootstrapping the first admin

Built-in policies

Managing IAM in the UI

What commonly goes wrong

Next steps

Permissions model

Permissions reference

Architecture

Create a cluster

​Authentication

​Modes

OIDC

AUTH_DISABLED

​The OIDC flow

​Session cookie

​Configuration

​Authorization (IAM)

​Enforcement

​KRN — resource names

​Policy document

​Evaluation order

​Groups

​Bootstrapping the first admin

​Built-in policies

​Managing IAM in the UI

​What commonly goes wrong

​Next steps

Permissions model

Permissions reference

Architecture

Create a cluster

Authentication

Modes

The OIDC flow

Session cookie

Configuration

Authorization (IAM)

Enforcement

KRN — resource names

Policy document

Evaluation order

Groups

Bootstrapping the first admin

Built-in policies

Managing IAM in the UI

What commonly goes wrong

Next steps