Torjus Håkestad
dd9571d83a
All checks were successful
Run nix flake check / flake-check (push) Successful in 2m0s
- Document UUID-based home directories with symlinks - List currently enabled hosts (testvm01-03) - Add cache-invalidate command to troubleshooting Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
216 lines
4.3 KiB
Markdown
216 lines
4.3 KiB
Markdown
# 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>
|
|
```
|