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 <username>
+
+# Set UNIX password (required for SSH login)
+kanidm person posix set-password <username>
+```
+
+## 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 <group-name> --gidnumber <gid>
+
+# 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 <username>
+
+# Check group resolution
+getent group <group-name>
+```
+
+### Test SSH Login
+
+```bash
+ssh <username>@<hostname>.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 <username>
+   ```

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";

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";

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";

system/default.nix

@@ -4,6 +4,7 @@
     ./acme.nix
     ./autoupgrade.nix
     ./homelab-deploy.nix
+    ./kanidm-client.nix
     ./monitoring
     ./motd.nix
     ./packages.nix

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";
+      };
+    };
+  };
+}