# 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:**
```nix
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:**
```nix
services.kanidm.provision.enable = true;
services.kanidm.provision.persons.torjus = {
  displayName = "Torjus";
  groups = [ "admins" "nas-users" ];
};
```

**Declarative OAuth2 clients:**
```nix
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/):**
```nix
services.kanidm.enableClient = true;
services.kanidm.enablePam = true;
services.kanidm.clientSettings.uri = "https://auth.home.2rjus.net";
```

## 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**
   - Verify UID/GID mapping works with NFS/SMB 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?
- Should LDAP interface be enabled for any legacy services?

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