# Authentication System Replacement Plan

## Overview

Deploy a modern, unified authentication solution for the homelab. Provides central user management, SSO for web services, and consistent UID/GID mapping for NAS permissions.

## Goals

1. **Central user database** - Manage users across all homelab hosts from a single source
2. **Linux PAM/NSS integration** - Users can SSH into hosts using central credentials
3. **UID/GID consistency** - Proper POSIX attributes for NAS share permissions
4. **OIDC provider** - Single sign-on for homelab web services (Grafana, etc.)

## Solution: Kanidm

Kanidm was chosen for the following reasons:

| Requirement | Kanidm Support |
|-------------|----------------|
| Central user database | Native |
| Linux PAM/NSS (host login) | Native NixOS module |
| UID/GID for NAS | POSIX attributes supported |
| OIDC for services | Built-in |
| Declarative config | Excellent NixOS provisioning |
| Simplicity | Modern API, LDAP optional |
| NixOS integration | First-class |

### Configuration Files

- **Host configuration:** `hosts/kanidm01/`
- **Service module:** `services/kanidm/default.nix`

## NAS Integration

### Current: TrueNAS CORE (FreeBSD)

TrueNAS CORE has a built-in LDAP client. Kanidm's read-only LDAP interface will work for NFS share permissions:

- **NFS shares**: Only need consistent UID/GID mapping - Kanidm's LDAP provides this
- **No SMB requirement**: SMB would need Samba schema attributes (deprecated in TrueNAS 13.0+), but we're NFS-only

Configuration approach:
1. Enable Kanidm's LDAP interface (`ldapbindaddress = "0.0.0.0:636"`)
2. Import internal CA certificate into TrueNAS
3. Configure TrueNAS LDAP client with Kanidm's Base DN and bind credentials
4. Users/groups appear in TrueNAS permission dropdowns

Note: Kanidm's LDAP is read-only and uses LDAPS only (no StartTLS). This is fine for our use case.

### Future: NixOS NAS

When the NAS is migrated to NixOS, it becomes a first-class citizen:

- Native Kanidm PAM/NSS integration (same as other hosts)
- No LDAP compatibility layer needed
- Full integration with the rest of the homelab

This future migration path is a strong argument for Kanidm over LDAP-only solutions.

## Implementation Steps

1. **Create kanidm01 host and service module** ✅
   - Host: `kanidm01.home.2rjus.net` (10.69.13.23, test tier)
   - Service module: `services/kanidm/`
   - TLS via internal ACME (`auth.home.2rjus.net`)
   - Vault integration for idm_admin password
   - LDAPS on port 636

2. **Configure declarative provisioning** ✅
   - Groups: `admins`, `users`, `ssh-users`
   - User: `torjus` (member of all groups)
   - POSIX attributes enabled (UID/GID range 65,536-69,999)

3. **Test NAS integration** (in progress)
   - ✅ LDAP interface verified working
   - Configure TrueNAS LDAP client to connect to Kanidm
   - Verify UID/GID mapping works with NFS shares

4. **Add OIDC clients** for homelab services
   - Grafana
   - Other services as needed

5. **Create client module** in `system/` for PAM/NSS
   - Enable on all hosts that need central auth
   - Configure trusted CA

6. **Documentation**
   - User management procedures
   - Adding new OAuth2 clients
   - Troubleshooting PAM/NSS issues

## Progress

### Completed (2026-02-08)

**Kanidm server deployed on kanidm01 (test tier):**
- Host: `kanidm01.home.2rjus.net` (10.69.13.23)
- WebUI: `https://auth.home.2rjus.net`
- LDAPS: port 636
- Valid certificate from internal CA

**Configuration:**
- Kanidm 1.8 with secret provisioning support
- Daily backups at 22:00 (7 versions retained)
- Vault integration for idm_admin password
- Prometheus monitoring scrape target configured

**Provisioned entities:**
- Groups: `admins`, `users`, `ssh-users`
- User: `torjus` (member of all groups, POSIX enabled with GID 65536)

**Verified working:**
- WebUI login with idm_admin
- LDAP bind and search with POSIX-enabled user
- LDAPS with valid internal CA certificate

### UID/GID Range (Resolved)

**Range: 65,536 - 69,999** (manually allocated)

- Users: 65,536 - 67,999 (up to ~2500 users)
- Groups: 68,000 - 69,999 (up to ~2000 groups)

Rationale:
- Starts at Kanidm's recommended minimum (65,536)
- Well above NixOS system users (typically <1000)
- Avoids Podman/container issues with very high GIDs

### Next Steps

1. Deploy to monitoring01 to enable Prometheus scraping
2. Configure TrueNAS LDAP client for NAS integration testing
3. Add OAuth2 clients (Grafana first)
4. Create PAM/NSS client module for other hosts

## References

- [Kanidm Documentation](https://kanidm.github.io/kanidm/stable/)
- [NixOS Kanidm Module](https://search.nixos.org/options?query=services.kanidm)
- [Kanidm PAM/NSS Integration](https://kanidm.github.io/kanidm/stable/pam_and_nsswitch.html)