SSO and Identities (Kanidm)

Kanidm 🡕 is the network’s identity provider: a single identity unlocks all services (SSO). The idm service runs on the HCS (and, optionally, as a replica in each zone).

Understanding how it works

The details of the mechanisms (native OIDC, authenticating reverse proxy, connection flow) are explained in Authentication and identities.

Identities and groups

Accounts and groups are provisioned in Kanidm from etc/config.yaml:

etc/config.yaml

users:
  alice:
    profile: "nix-admin"
    groups: ["idm-admins", "idm-devs", "global"]

• Groups control access to services.
• Two special groups: idm-admins (administration), idm-devs (development).

Connect a service (OIDC)

OIDC-compatible services are linked to SSO automatically: Kanidm provisions an OAuth2 client per service, and its secret is managed by sops. Nothing to configure manually.

Examples

Outline, Mealie, Vaultwarden, Grafana, Immich, Forgejo, Jellyfin, Open WebUI…

Protecting a service without OIDC

A service without its own authentication (homepage, static site) is protected by placing a Kanidm login screen in front of it (oauth2-proxy + Caddy). For the homepage, a setting on the gateway host (usr/machines/<gateway>/) :

darkone.service.homepage.protect = true; # requires a Kanidm session

Option	Default	Effect
protect	true	Homepage reserved for Kanidm users (users group)

Prerequisites

The idm service must be running (HCS) and the homepage service must be present in the zone: it serves as the anchor for the login flow. The operation is detailed in Authentication and identities.

Resilient startup

oauth2-proxy needs to reach the OIDC issuer (Kanidm on the HCS) at its startup. If it is temporarily unreachable (typically right after an HCS rebuild), the proxy waits for the issuer to respond, and never gives up: it retries until recovery. No need to manually restart a deployment, the service heals itself.

Multi-zone replication

Not yet functional

Multi-zone replication is under development and is not operational. For now, declare idm on the HCS only.

The mode is inferred from where idm is declared:

1. idm on the HCS only → single instance, no replication.
2. idm on a gateway without HCS → standalone instance in the zone.
3. idm on the HCS and gateways → replication: the HCS provides, each gateway is a read-only replica.

Two-step bootstrap (scenario 3)

1. just apply: each node generates its replication certificate.
2. just idm-sync-certs then just apply: gateways switch to read-only (pull from the HCS).

Administration

Administration is done via the command line on the HCS:

just enter hcs
kanidm person credential create-reset-token <login> --name idm_admin

See Create a user account and Reset a password.

Updating Kanidm

Kanidm only maintains a single version at a time : a version reaches its end-of-life 30 days after the release of the next one, and only an upgrade from one version to the next is supported. DNF therefore pins the package explicitly, in dnf/modules/service/idm.nix :

services.kanidm.package = pkgs.kanidm_1_11.withSecretProvisioning;

The evaluation warns as soon as the pinned version is deprecated :

kanidm 1.10 is deprecated and will reach end-of-life on 2026-08-31

After this date, nixpkgs marks the version as unmaintained and the evaluation fails. The upgrade must therefore be planned before the deadline.

No automatic rollback

The database is migrated on the first start of the new version, with no downgrade possible. Back up before, and never skip a version (an upgrade 1.10 → 1.12 must go through 1.11).

1. Compatibility check, on the HCS, before touching the version :

   just enter hcs
   sudo kanidmd domain upgrade-check -c /etc/kanidm/server.toml

   Read-only operation. Each item must come out as PASS ; a FAIL must be fixed before going any further.

2. Cold copy of the database, the only really reliable rollback :

   sudo systemctl stop kanidm
   sudo install -d -o kanidm -g kanidm /var/lib/kanidm/pre-upgrade
   sudo cp -a /var/lib/kanidm/kanidm.db* /var/lib/kanidm/pre-upgrade/
   sudo kanidmd database backup /var/lib/kanidm/pre-upgrade/dump.json -c /etc/kanidm/server.toml
   sudo chown -R kanidm:kanidm /var/lib/kanidm
   sudo systemctl start kanidm

   Copy the journal, not just the database. SQLite does not always merge its write journal when closing : a kanidm.db-wal of several MB commonly survives the service stop. Copying kanidm.db alone would leave the latest transactions aside. The * takes the .db, .db-wal and .db-shm triplet, which is only valid taken together.

   The final chown is not optional : the two previous commands run as root and would otherwise leave files the service can no longer write.

3. Move the pin to the next version, one at a time, then deploy the HCS.

4. Check the service and the database consistency :

   systemctl status kanidm
   sudo kanidmd database verify -c /etc/kanidm/server.toml

   Finish with a real OIDC login on a network service.

In case of failure : put the pin back on the previous version, restore the .bak file in place of kanidm.db (service stopped), redeploy.