Torjus Håkestad
93dbb45802
- Mark completed implementation steps - Document deployed kanidm01 configuration - Record UID/GID range decision (65,536-69,999) - Add verified working items (WebUI, LDAP, certs) - Update next steps and resolved questions Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
141 lines
4.6 KiB
Markdown
141 lines
4.6 KiB
Markdown
# 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)
|