docs: add user-management documentation

- CLI workflows for creating users and groups - Troubleshooting guide (nscd, cache invalidation) - Home directory behavior (UUID-based with symlinks) - Update auth-system-replacement plan with progress Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-08 14:27:15 +01:00
parent b31c64f1b9
commit 9ed09c9a9c
2 changed files with 179 additions and 52 deletions
--- a/docs/plans/auth-system-replacement.md
+++ b/docs/plans/auth-system-replacement.md
@@ -66,9 +66,9 @@ This future migration path is a strong argument for Kanidm over LDAP-only soluti
   - Vault integration for idm_admin password
   - LDAPS on port 636

-2. **Configure declarative provisioning** ✅
-   - Groups: `admins`, `users`, `ssh-users`
-   - User: `torjus` (member of all groups)
+2. **Configure provisioning** ✅
+   - Groups provisioned declaratively: `admins`, `users`, `ssh-users`
+   - Users managed imperatively via CLI (allows setting POSIX passwords in one step)
   - POSIX attributes enabled (UID/GID range 65,536-69,999)

 3. **Test NAS integration** (in progress)
@@ -80,14 +80,16 @@ This future migration path is a strong argument for Kanidm over LDAP-only soluti
   - Grafana
   - Other services as needed

-5. **Create client module** in `system/` for PAM/NSS
-   - Enable on all hosts that need central auth
-   - Configure trusted CA
+5. **Create client module** in `system/` for PAM/NSS ✅
+   - Module: `system/kanidm-client.nix`
+   - `homelab.kanidm.enable = true` enables PAM/NSS
+   - Short usernames (not SPN format)
+   - Home directory symlinks via `home_alias`
+   - Enabled on test tier: testvm01, testvm02, testvm03

-6. **Documentation**
-   - User management procedures
-   - Adding new OAuth2 clients
-   - Troubleshooting PAM/NSS issues
+6. **Documentation** ✅
+   - `docs/user-management.md` - CLI workflows, troubleshooting
+   - User/group creation procedures verified working

 ## Progress

@@ -106,14 +108,37 @@ This future migration path is a strong argument for Kanidm over LDAP-only soluti
 - Prometheus monitoring scrape target configured

 **Provisioned entities:**
- Groups: `admins`, `users`, `ssh-users`
- User: `torjus` (member of all groups, POSIX enabled with GID 65536)
+- Groups: `admins`, `users`, `ssh-users` (declarative)
+- Users managed via CLI (imperative)

 **Verified working:**
 - WebUI login with idm_admin
 - LDAP bind and search with POSIX-enabled user
 - LDAPS with valid internal CA certificate

+### Completed (2026-02-08) - PAM/NSS Client
+
+**Client module deployed (`system/kanidm-client.nix`):**
+- `homelab.kanidm.enable = true` enables PAM/NSS integration
+- Connects to auth.home.2rjus.net
+- Short usernames (`torjus` instead of `torjus@home.2rjus.net`)
+- Home directory symlinks (`/home/torjus` → UUID-based dir)
+- Login restricted to `ssh-users` group
+
+**Enabled on test tier:**
+- testvm01, testvm02, testvm03
+
+**Verified working:**
+- User/group resolution via `getent`
+- SSH login with Kanidm unix passwords
+- Home directory creation with symlinks
+- Imperative user/group creation via CLI
+
+**Documentation:**
+- `docs/user-management.md` with full CLI workflows
+- Password requirements (min 10 chars)
+- Troubleshooting guide (nscd, cache invalidation)
+
 ### UID/GID Range (Resolved)

 **Range: 65,536 - 69,999** (manually allocated)
@@ -128,10 +153,9 @@ Rationale:

 ### Next Steps

-1. Deploy to monitoring01 to enable Prometheus scraping
+1. Enable PAM/NSS on production hosts (after test tier validation)
 2. Configure TrueNAS LDAP client for NAS integration testing
 3. Add OAuth2 clients (Grafana first)
-4. Create PAM/NSS client module for other hosts

 ## References

--- a/docs/user-management.md
+++ b/docs/user-management.md
@@ -21,61 +21,113 @@ kanidm login --name idm_admin --url https://auth.home.2rjus.net

 ## User Management

-### Creating Users
+POSIX users are managed imperatively via the `kanidm` CLI. This allows setting
+all attributes (including UNIX password) in one workflow.

-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:
+### Creating a POSIX User

 ```bash
-# Check if user has POSIX enabled
-kanidm person get <username>
+# Create the person
+kanidm person create <username> "<Display Name>"

-# Set UNIX password (required for SSH login)
+# Add to groups
+kanidm group add-members ssh-users <username>
+
+# Enable POSIX (UID is auto-assigned)
+kanidm person posix set <username>
+
+# Set UNIX password (required for SSH login, min 10 characters)
 kanidm person posix set-password <username>
+
+# Optionally set login shell
+kanidm person posix set <username> --shell /bin/zsh
+```
+
+### Example: Full User Creation
+
+```bash
+kanidm person create testuser "Test User"
+kanidm group add-members ssh-users testuser
+kanidm person posix set testuser
+kanidm person posix set-password testuser
+kanidm person get testuser
+```
+
+After creation, verify on a client host:
+```bash
+getent passwd testuser
+ssh testuser@testvm01.home.2rjus.net
+```
+
+### Viewing User Details
+
+```bash
+kanidm person get <username>
+```
+
+### Removing a User
+
+```bash
+kanidm person delete <username>
 ```

 ## Group Management

-### Creating Groups
+Groups for POSIX access are also managed via CLI.

-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:
+### Creating a POSIX Group

 ```bash
-# Enable POSIX on a group with a specific GID
-kanidm group posix set <group-name> --gidnumber <gid>
+# Create the group
+kanidm group create <group-name>

-# Example: enable ssh-users group
-kanidm group posix set ssh-users --gidnumber 68000
+# Enable POSIX with a specific GID
+kanidm group posix set <group-name> --gidnumber <gid>
 ```

+### Adding Members
+
+```bash
+kanidm group add-members <group-name> <username>
+```
+
+### Viewing Group Details
+
+```bash
+kanidm group get <group-name>
+kanidm group list-members <group-name>
+```
+
+### Example: Full Group Creation
+
+```bash
+kanidm group create testgroup
+kanidm group posix set testgroup --gidnumber 68010
+kanidm group add-members testgroup testuser
+kanidm group get testgroup
+```
+
+After creation, verify on a client host:
+```bash
+getent group testgroup
+```
+
+### Current Groups
+
+| Group | GID | Purpose |
+|-------|-----|---------|
+| ssh-users | 68000 | SSH login access |
+| admins | 68001 | Administrative access |
+| users | 68002 | General users |
+
 ### UID/GID Allocation

+Kanidm auto-assigns UIDs/GIDs from its configured range. For manually assigned GIDs:
+
 | Range | Purpose |
 |-------|---------|
-| 65,536 - 67,999 | Users |
-| 68,000 - 69,999 | Groups |
+| 65,536+ | Users (auto-assigned) |
+| 68,000 - 68,999 | Groups (manually assigned) |

 ## PAM/NSS Client Configuration

@@ -89,6 +141,12 @@ This configures:
 - `services.kanidm.enablePam = true`
 - Client connection to auth.home.2rjus.net
 - Login authorization for `ssh-users` group
+- Short usernames (`torjus` instead of `torjus@home.2rjus.net`)
+- Home directory symlinks (`/home/torjus` → UUID-based directory)
+
+### Enabled Hosts
+
+- testvm01, testvm02, testvm03 (test tier)

 ### Options

@@ -100,6 +158,17 @@ homelab.kanidm = {
 };
 ```

+### Home Directories
+
+Home directories use UUID-based paths for stability (so renaming a user doesn't
+require moving their home directory). Symlinks provide convenient access:
+
+```
+/home/torjus -> /home/e4f4c56c-4aee-4c20-846f-90cb69807733
+```
+
+The symlinks are created by `kanidm-unixd-tasks` on first login.
+
 ## Testing

 ### Verify NSS Resolution
@@ -153,12 +222,46 @@ kanidm group posix set ssh-users --gidnumber 68000
   systemctl status kanidm-unixd
   ```

-2. Check client can reach server:
+2. Check unixd can reach server:
+   ```bash
+   kanidm-unix status
+   # Should show: system: online, Kanidm: online
+   ```
+
+3. Check client can reach server:
   ```bash
   curl -s https://auth.home.2rjus.net/status
   ```

-3. Check user has POSIX enabled on server:
+4. Check user has POSIX enabled on server:
   ```bash
   kanidm person get <username>
   ```
+
+5. Restart nscd to clear stale cache:
+   ```bash
+   systemctl restart nscd
+   ```
+
+6. Invalidate kanidm cache:
+   ```bash
+   kanidm-unix cache-invalidate
+   ```
+
+### Changes not taking effect after deployment
+
+NixOS uses nsncd (a Rust reimplementation of nscd) for NSS caching. After deploying
+kanidm-unixd config changes, you may need to restart both services:
+
+```bash
+systemctl restart kanidm-unixd
+systemctl restart nscd
+```
+
+### Test PAM authentication directly
+
+Use the kanidm-unix CLI to test PAM auth without SSH:
+
+```bash
+kanidm-unix auth-test --name <username>
+```