From b845a8bb8b9cbad365fc4a491d67166eb7694e51 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torjus=20H=C3=A5kestad?= Date: Sun, 8 Feb 2026 13:43:41 +0100 Subject: [PATCH] system: add kanidm PAM/NSS client module Add homelab.kanidm.enable option for central authentication via Kanidm. The module configures: - PAM/NSS integration with kanidm-unixd - Client connection to auth.home.2rjus.net - Login authorization for ssh-users group Enable on testvm01-03 for testing. Co-Authored-By: Claude Opus 4.5 --- docs/user-management.md | 164 +++++++++++++++++++++++++++++++ hosts/testvm01/configuration.nix | 3 + hosts/testvm02/configuration.nix | 3 + hosts/testvm03/configuration.nix | 3 + system/default.nix | 1 + system/kanidm-client.nix | 42 ++++++++ 6 files changed, 216 insertions(+) create mode 100644 docs/user-management.md create mode 100644 system/kanidm-client.nix diff --git a/docs/user-management.md b/docs/user-management.md new file mode 100644 index 0000000..b45411c --- /dev/null +++ b/docs/user-management.md @@ -0,0 +1,164 @@ +# User Management with Kanidm + +Central authentication for the homelab using Kanidm. + +## Overview + +- **Server**: kanidm01.home.2rjus.net (auth.home.2rjus.net) +- **WebUI**: https://auth.home.2rjus.net +- **LDAPS**: port 636 + +## CLI Setup + +The `kanidm` CLI is available in the devshell: + +```bash +nix develop + +# Login as idm_admin +kanidm login --name idm_admin --url https://auth.home.2rjus.net +``` + +## User Management + +### Creating Users + +Users are provisioned declaratively in `services/kanidm/default.nix`: + +```nix +services.kanidm.provision.persons.username = { + displayName = "Display Name"; + groups = [ "admins" "users" "ssh-users" ]; +}; +``` + +### Enabling POSIX for Users + +For PAM/NSS integration, users need POSIX attributes and a UNIX password: + +```bash +# Check if user has POSIX enabled +kanidm person get + +# Set UNIX password (required for SSH login) +kanidm person posix set-password +``` + +## Group Management + +### Creating Groups + +Groups are provisioned declaratively: + +```nix +services.kanidm.provision.groups = { + admins = { }; + users = { }; + ssh-users = { }; +}; +``` + +### Enabling POSIX for Groups + +Groups must have POSIX enabled to be resolved via NSS: + +```bash +# Enable POSIX on a group with a specific GID +kanidm group posix set --gidnumber + +# Example: enable ssh-users group +kanidm group posix set ssh-users --gidnumber 68000 +``` + +### UID/GID Allocation + +| Range | Purpose | +|-------|---------| +| 65,536 - 67,999 | Users | +| 68,000 - 69,999 | Groups | + +## PAM/NSS Client Configuration + +Enable central authentication on a host: + +```nix +homelab.kanidm.enable = true; +``` + +This configures: +- `services.kanidm.enablePam = true` +- Client connection to auth.home.2rjus.net +- Login authorization for `ssh-users` group + +### Options + +```nix +homelab.kanidm = { + enable = true; + server = "https://auth.home.2rjus.net"; # default + allowedLoginGroups = [ "ssh-users" ]; # default +}; +``` + +## Testing + +### Verify NSS Resolution + +```bash +# Check user resolution +getent passwd + +# Check group resolution +getent group +``` + +### Test SSH Login + +```bash +ssh @.home.2rjus.net +``` + +## Troubleshooting + +### "PAM user mismatch" error + +SSH fails with "fatal: PAM user mismatch" in logs. This happens when Kanidm returns +usernames in SPN format (`torjus@home.2rjus.net`) but SSH expects short names (`torjus`). + +**Solution**: Configure `uid_attr_map = "name"` in unixSettings (already set in our module). + +Check current format: +```bash +getent passwd torjus +# Should show: torjus:x:65536:... +# NOT: torjus@home.2rjus.net:x:65536:... +``` + +### User resolves but SSH fails immediately + +The user's login group (e.g., `ssh-users`) likely doesn't have POSIX enabled: + +```bash +# Check if group has POSIX +getent group ssh-users + +# If empty, enable POSIX on the server +kanidm group posix set ssh-users --gidnumber 68000 +``` + +### User doesn't resolve via getent + +1. Check kanidm-unixd service is running: + ```bash + systemctl status kanidm-unixd + ``` + +2. Check client can reach server: + ```bash + curl -s https://auth.home.2rjus.net/status + ``` + +3. Check user has POSIX enabled on server: + ```bash + kanidm person get + ``` diff --git a/hosts/testvm01/configuration.nix b/hosts/testvm01/configuration.nix index ee93d4a..0fe1fa5 100644 --- a/hosts/testvm01/configuration.nix +++ b/hosts/testvm01/configuration.nix @@ -25,6 +25,9 @@ # Enable remote deployment via NATS homelab.deploy.enable = true; + # Enable Kanidm PAM/NSS for central authentication + homelab.kanidm.enable = true; + nixpkgs.config.allowUnfree = true; boot.loader.grub.enable = true; boot.loader.grub.device = "/dev/vda"; diff --git a/hosts/testvm02/configuration.nix b/hosts/testvm02/configuration.nix index 5e6f11b..d63e5b5 100644 --- a/hosts/testvm02/configuration.nix +++ b/hosts/testvm02/configuration.nix @@ -25,6 +25,9 @@ # Enable remote deployment via NATS homelab.deploy.enable = true; + # Enable Kanidm PAM/NSS for central authentication + homelab.kanidm.enable = true; + nixpkgs.config.allowUnfree = true; boot.loader.grub.enable = true; boot.loader.grub.device = "/dev/vda"; diff --git a/hosts/testvm03/configuration.nix b/hosts/testvm03/configuration.nix index 6fd9b48..cd0789d 100644 --- a/hosts/testvm03/configuration.nix +++ b/hosts/testvm03/configuration.nix @@ -25,6 +25,9 @@ # Enable remote deployment via NATS homelab.deploy.enable = true; + # Enable Kanidm PAM/NSS for central authentication + homelab.kanidm.enable = true; + nixpkgs.config.allowUnfree = true; boot.loader.grub.enable = true; boot.loader.grub.device = "/dev/vda"; diff --git a/system/default.nix b/system/default.nix index 9ba5d06..4ab14ac 100644 --- a/system/default.nix +++ b/system/default.nix @@ -4,6 +4,7 @@ ./acme.nix ./autoupgrade.nix ./homelab-deploy.nix + ./kanidm-client.nix ./monitoring ./motd.nix ./packages.nix diff --git a/system/kanidm-client.nix b/system/kanidm-client.nix new file mode 100644 index 0000000..c720aa7 --- /dev/null +++ b/system/kanidm-client.nix @@ -0,0 +1,42 @@ +{ lib, config, pkgs, ... }: +let + cfg = config.homelab.kanidm; +in +{ + options.homelab.kanidm = { + enable = lib.mkEnableOption "Kanidm PAM/NSS client for central authentication"; + + server = lib.mkOption { + type = lib.types.str; + default = "https://auth.home.2rjus.net"; + description = "URI of the Kanidm server"; + }; + + allowedLoginGroups = lib.mkOption { + type = lib.types.listOf lib.types.str; + default = [ "ssh-users" ]; + description = "Groups allowed to log in via PAM"; + }; + }; + + config = lib.mkIf cfg.enable { + services.kanidm = { + package = pkgs.kanidm_1_8; + enablePam = true; + + clientSettings = { + uri = cfg.server; + }; + + unixSettings = { + pam_allowed_login_groups = cfg.allowedLoginGroups; + # Use short names (torjus) instead of SPN format (torjus@home.2rjus.net) + # This prevents "PAM user mismatch" errors with SSH + uid_attr_map = "name"; + gid_attr_map = "name"; + # Create symlink /home/torjus -> /home/torjus@home.2rjus.net + home_alias = "name"; + }; + }; + }; +}