AZ-NIX-CLIENTS/docs/superpowers/specs/2026-08-12-az-tc-01-ad-wifi-bootstrap-design.md

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.