nixos-servers/docs/plans/auth-system-replacement.md

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
• NixOS Kanidm Module
• Kanidm PAM/NSS Integration