# 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

### Creating Users

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:

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

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

### Enabling POSIX for Groups

Groups must have POSIX enabled to be resolved via NSS:

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

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