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 <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>
+   ```
diff --git a/system/kanidm-client.nix b/system/kanidm-client.nix
index bae7956..c5921de 100644
--- a/system/kanidm-client.nix
+++ b/system/kanidm-client.nix
@@ -30,6 +30,9 @@ in
 
       unixSettings = {
         pam_allowed_login_groups = cfg.allowedLoginGroups;
+        # Use short names (e.g., "torjus") instead of SPN (e.g., "torjus@home.2rjus.net")
+        uid_attr_map = "name";
+        gid_attr_map = "name";
       };
     };
   };