docs(thin-client): design AD and WiFi bootstrap

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-08-12 11:45:18 +02:00
parent c71aba5f64
commit 828399e379
1 changed files with 76 additions and 0 deletions
@@ -0,0 +1,76 @@
 # AZ-TC-01 AD and WiFi bootstrap design
 ## Goal
 Bring `AZ-TC-01` online as a reproducible pilot in two independent stages:
 1. Integrate the host with Active Directory.
 2. Connect it temporarily to the WPA-Personal network `Pluto` using a shared password.
 Certificate-based access to the `Saturn` network remains out of scope until AD is proven functional.
 ## Host profile
 `AZ-TC-01` remains on the `staging` site so unrelated production integrations stay disabled. Only AD and WiFi are enabled explicitly.
 The host uses these confirmed infrastructure values:
 - AD DNS domain: `az-group.local`
 - Kerberos realm: `AZ-GROUP.LOCAL`
 - Primary domain controller: `azdc01.az-group.local` (`192.168.152.253`)
 - Secondary domain controller: `adpdc01.az-group.local` (`192.168.152.254`)
 - Computer location: default `CN=Computers,DC=az-group,DC=local` container
 - Temporary WPA-Personal SSID: `Pluto`
 ## Active Directory bootstrap
 An administrator creates or joins the `AZ-TC-01` computer account from an admin workstation that can reach the domain controllers. `adcli` writes a binary host keytab for `AZ-TC-01.az-group.local` without altering the admin workstation's own keytab.
 The binary keytab is encrypted directly from the file into `secrets/AZ-TC-01-krb5-keytab.age`; it must never be copied through a text editor. The current encrypted placeholder is replaced. Before deployment, the decrypted result is checked with `klist -k -e` and must contain machine and host principals in `AZ-GROUP.LOCAL`.
 At boot, agenix decrypts it to `/etc/krb5.keytab` with mode `0600`. SSSD starts only after the age identity is available. Runtime verification covers Kerberos keytab readability, SSSD domain status, identity lookup, and an interactive AD login.
 ## Temporary WPA-Personal WiFi
 The WiFi module supports two explicit modes:
 - `psk`: WPA-Personal using a per-host agenix secret.
 - `eap-tls`: the existing certificate-based configuration for the later `Saturn` rollout.
 For this pilot, `AZ-TC-01` selects `psk` and SSID `Pluto`. The shared password is entered locally into `secrets/AZ-TC-01-wifi-psk.age`; it is never sent in chat or stored in Nix source.
 Agenix decrypts the password to a root-only runtime file. NetworkManager obtains the PSK at activation time without placing its plaintext in the Nix store. Enabling `psk` requires only the PSK secret; enabling `eap-tls` requires only the client certificate secret. This keeps the deferred `Saturn` certificate from blocking the pilot.
 ## Secret and deployment flow
 The existing dedicated host age identity remains the recipient for both per-host secrets:
 - `AZ-TC-01-krb5-keytab.age`
 - `AZ-TC-01-wifi-psk.age`
 The deployment preflight evaluates the enabled features, confirms each required encrypted file exists, and verifies that the injected host identity can decrypt it. The identity is copied to `/var/lib/agenix/identity.age` during installation.
 ## Validation
 Before touching the target disk:
 1. Evaluate the host configuration and inspect its required secrets.
 2. Validate the decrypted keytab with `klist -k -e`.
 3. Run the deployment wrapper's non-destructive preflight.
 4. Run the Nix flake checks and build the host closure.
 After boot:
 1. Confirm NetworkManager is connected to `Pluto` and DNS resolves both domain controllers.
 2. Confirm Kerberos ports and time synchronization are available.
 3. Check `systemctl status sssd` and `sssctl domain-status az-group.local`.
 4. Resolve an AD user with `getent passwd` and `id`.
 5. Perform an SDDM login with an AD account and verify offline credential caching only after one successful online login.
 ## Failure handling and rollback
 - A missing or undecryptable required secret blocks deployment.
 - An invalid keytab prevents SSSD startup and is diagnosed before deployment with `klist`.
 - AD and WiFi stay independently switchable, so either can be disabled while diagnosing the other.
 - Returning the host to base staging requires setting both feature flags to `false`; no production integrations are enabled implicitly.
 - The future migration to `Saturn` changes the WiFi mode to `eap-tls`, replaces the SSID, installs the trusted RADIUS CA, and adds the client certificate secret. It does not alter the AD design.