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:

```bash
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

```bash
# 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

Groups for POSIX access are also managed via CLI.

### Creating a POSIX Group

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

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

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

```nix
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

```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 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
   ```

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>
```