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

Authentication System Replacement Plan

Overview

Replace the current auth01 setup (LLDAP + Authelia) with a modern, unified authentication solution. The current setup is not in active use, making this a good time to evaluate alternatives.

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.)

Options Evaluated

OpenLDAP (raw)

• NixOS Support: Good (services.openldap with declarativeContents)
• Pros: Most widely supported, very flexible
• Cons: LDIF format is painful, schema management is complex, no built-in OIDC, requires SSSD on each client
• Verdict: Doesn't address LDAP complexity concerns

LLDAP + Authelia (current)

• NixOS Support: Both have good modules
• Pros: Already configured, lightweight, nice web UIs
• Cons: Two services to manage, limited POSIX attribute support in LLDAP, requires SSSD on every client host
• Verdict: Workable but has friction for NAS/UID goals

FreeIPA

• NixOS Support: None
• Pros: Full enterprise solution (LDAP + Kerberos + DNS + CA)
• Cons: Extremely heavy, wants to own DNS, designed for Red Hat ecosystems, massive overkill for homelab
• Verdict: Overkill, no NixOS support

Keycloak

• NixOS Support: None
• Pros: Good OIDC/SAML, nice UI
• Cons: Primarily an identity broker not a user directory, poor POSIX support, heavy (Java)
• Verdict: Wrong tool for Linux user management

Authentik

• NixOS Support: None (would need Docker)
• Pros: All-in-one with LDAP outpost and OIDC, modern UI
• Cons: Heavy stack (Python + PostgreSQL + Redis), LDAP is a separate component
• Verdict: Would work but requires Docker and is heavy

Kanidm

• NixOS Support: Excellent - first-class module with PAM/NSS integration
• Pros:
  • Native PAM/NSS module (no SSSD needed)
  • Built-in OIDC provider
  • Optional LDAP interface for legacy services
  • Declarative provisioning via NixOS (users, groups, OAuth2 clients)
  • Modern, written in Rust
  • Single service handles everything
• Cons: Newer project, smaller community than LDAP
• Verdict: Best fit for requirements

Pocket-ID

• NixOS Support: Unknown
• Pros: Very lightweight, passkey-first
• Cons: No LDAP, no PAM/NSS integration - purely OIDC for web apps
• Verdict: Doesn't solve Linux user management goal

Recommendation: Kanidm

Kanidm is the recommended solution 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

Key NixOS Features

Server configuration:

services.kanidm.enableServer = true;
services.kanidm.serverSettings = {
  domain = "home.2rjus.net";
  origin = "https://auth.home.2rjus.net";
  ldapbindaddress = "0.0.0.0:636";  # Optional LDAP interface
};

Declarative user provisioning:

services.kanidm.provision.enable = true;
services.kanidm.provision.persons.torjus = {
  displayName = "Torjus";
  groups = [ "admins" "nas-users" ];
};

Declarative OAuth2 clients:

services.kanidm.provision.systems.oauth2.grafana = {
  displayName = "Grafana";
  originUrl = "https://grafana.home.2rjus.net/login/generic_oauth";
  originLanding = "https://grafana.home.2rjus.net";
};

Client host configuration (add to system/):

services.kanidm.enableClient = true;
services.kanidm.enablePam = true;
services.kanidm.clientSettings.uri = "https://auth.home.2rjus.net";

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 Kanidm service module in services/kanidm/

   • Server configuration
   • TLS via internal ACME
   • Vault secrets for admin passwords

2. Configure declarative provisioning

   • Define initial users and groups
   • Set up POSIX attributes (UID/GID ranges)

3. Add OIDC clients for homelab services

   • Grafana
   • Other services as needed

4. Create client module in system/ for PAM/NSS

   • Enable on all hosts that need central auth
   • Configure trusted CA

5. Test NAS integration

   • Configure TrueNAS LDAP client to connect to Kanidm
   • Verify UID/GID mapping works with NFS shares

6. Migrate auth01

   • Remove LLDAP and Authelia services
   • Deploy Kanidm
   • Update DNS CNAMEs if needed

7. Documentation

   • User management procedures
   • Adding new OAuth2 clients
   • Troubleshooting PAM/NSS issues

Open Questions

• What UID/GID range should be reserved for Kanidm-managed users?
• Which hosts should have PAM/NSS enabled initially?
• What OAuth2 clients are needed at launch?

References

• Kanidm Documentation
• NixOS Kanidm Module
• Kanidm PAM/NSS Integration