From 71a41d83ef900b7b32314a36ccaa5d378afd063d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Torjus=20H=C3=A5kestad?= <torjus@usit.uio.no>
Date: Sun, 8 Feb 2026 14:51:08 +0100
Subject: [PATCH] docs: switch to imperative user/group management

Replace declarative NixOS provisioning examples with full CLI workflows.
POSIX users and groups are now managed entirely via kanidm CLI, which
allows setting all attributes (including UNIX passwords) in one step.

Declarative provisioning may still be used for OIDC clients later.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/user-management.md | 93 +++++++++++++++++++++++++----------------
 1 file changed, 58 insertions(+), 35 deletions(-)

diff --git a/docs/user-management.md b/docs/user-management.md
index e2334dc..2026915 100644
--- a/docs/user-management.md
+++ b/docs/user-management.md
@@ -21,61 +21,84 @@ 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>"
+
+# Add to groups
+kanidm group add-members ssh-users <username>
+kanidm group add-members users <username>
+
+# Enable POSIX (UID is auto-assigned from Kanidm's range)
+kanidm person posix set <username>
 
 # Set UNIX password (required for SSH login)
 kanidm person posix set-password <username>
+
+# Optionally set login shell
+kanidm person posix set <username> --shell /bin/zsh
+```
+
+### 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>
+```
+
+### 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