Files

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>

2026-02-08 15:12:19 +01:00

4.8 KiB

Raw Blame History

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:

nix develop

# Login as idm_admin
kanidm login --name idm_admin --url https://auth.home.2rjus.net

User Management

POSIX users are managed imperatively via the kanidm CLI. This allows setting all attributes (including UNIX password) in one workflow.

Creating a POSIX User

# 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

kanidm person get <username>

Removing a User

kanidm person delete <username>

Group Management

Groups for POSIX access are also managed via CLI.

Creating a POSIX Group

# Create the group
kanidm group create <group-name>

# Enable POSIX with a specific GID
kanidm group posix set <group-name> --gidnumber <gid>

Adding Members

kanidm group add-members <group-name> <username>

Viewing Group Details

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+	Users (auto-assigned)
68,000 - 68,999	Groups (manually assigned)

PAM/NSS Client Configuration

Enable central authentication on a host:

homelab.kanidm.enable = true;

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

homelab.kanidm = {
  enable = true;
  server = "https://auth.home.2rjus.net";  # default
  allowedLoginGroups = [ "ssh-users" ];     # default
};

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

# Check user resolution
getent passwd <username>

# Check group resolution
getent group <group-name>

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:

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:

# 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

Check kanidm-unixd service is running:
```
systemctl status kanidm-unixd
```

Check unixd can reach server:

kanidm-unix status
# Should show: system: online, Kanidm: online

Check client can reach server:

curl -s https://auth.home.2rjus.net/status

Check user has POSIX enabled on server:
```
kanidm person get <username>
```
Restart nscd to clear stale cache:
```
systemctl restart nscd
```
Invalidate kanidm cache:
```
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:

systemctl restart kanidm-unixd
systemctl restart nscd

Test PAM authentication directly

Use the kanidm-unix CLI to test PAM auth without SSH:

kanidm-unix auth-test --name <username>

4.8 KiB Raw Blame History