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…

Protect a service without OIDC

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

darkone.service.homepage.protect = true;             # requires a Kanidm session
darkone.service.homepage.protectExternalOnly = true; # internal free, external authenticated

Option	Default	Effect
protect	true	Homepage restricted to Kanidm users (users group)
protectExternalOnly	false	LAN/VPN without login, login required from outside

Prerequisites

The idm service must be running (HCS) and the homepage service must be present in the zone: it acts as the anchor for the connection flow. The details are explained in Authentication and identities.

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.