nixos-servers/docs/user-management.md

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

Creating Users

Users are provisioned declaratively in services/kanidm/default.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:

# 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:

services.kanidm.provision.groups = {
  admins = { };
  users = { };
  ssh-users = { };
};

Enabling POSIX for Groups

Groups must have POSIX enabled to be resolved via NSS:

# 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:

homelab.kanidm.enable = true;

This configures:

• services.kanidm.enablePam = true
• Client connection to auth.home.2rjus.net
• Login authorization for ssh-users group

Options

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

Testing

Verify NSS Resolution

# Check user resolution
getent passwd <username>

# Check group resolution
getent group <group-name>

Test SSH Login

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

1. Check kanidm-unixd service is running:

   systemctl status kanidm-unixd
   

2. Check unixd can reach server:

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

3. Check client can reach server:

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

4. Check user has POSIX enabled on server:

   kanidm person get <username>
   

5. Restart nscd to clear stale cache:

   systemctl restart nscd
   

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>