docs: record UniFi SSO login change and Ansible management (W1N-51)

docs/unifi-network.md

@@ -13,6 +13,32 @@
 Although `8080` is a common UniFi inform port, this controller uses `9080`.
 All AP adoption and recovery procedures must use the endpoint above.
 
+## Login and MFA
+
+On 2026-08-08, **"Sync Local Admin with Ubiquiti SSO"** was disabled
+(`super_sdn.sso_login_enabled: false`). Previously every login was forced
+through Ubiquiti SSO (sso.ui.com) and required MFA, which blocked programmatic
+access: the `unifi-network-mcp` write operations failed with
+`api.err.Ubic2faTokenRequired`.
+
+Now local accounts (`windy`, `zhiqiangf`) sign in with their local passwords
+and no MFA. The `unifi-network-mcp` tool uses the `zhiqiangf` local account and
+works for both read and write operations (verified 2026-08-08 with a reversible
+client rename).
+
+Impact: unifi.ui.com remote access (Site Manager) no longer works.
+
+Manage the setting idempotently via Ansible:
+
+```bash
+cd ansible
+ansible-playbook playbooks/unifi-sso.yml --limit unifi --check   # read-only
+ansible-playbook playbooks/unifi-sso.yml --limit unifi \
+  -e '{"unifi_sso_confirm": true, "unifi_sso_target_value": false}'  # apply
+```
+
+See [runbooks/ansible-operations.md](../runbooks/ansible-operations.md).
+
 ## Inter-VLAN reachability
 
 The AP management networks are routed by [gw](../hosts/gw.md),

hosts/ubnt.md

@@ -64,3 +64,16 @@ curl -k -sS -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8443/
 
 Recreating the service briefly interrupts the controller. Do not use `docker
 compose down -v`; it can remove persistent data.
+
+## Ansible management
+
+The host is in the Ansible `unifi` group (inventory `ansible/inventory/hosts.yml`),
+deliberately outside `managed` so the generic health report does not run here.
+
+- SSO login setting (idempotent, gated): `cd ansible && ansible-playbook
+  playbooks/unifi-sso.yml --limit unifi` — see
+  [runbooks/ansible-operations.md](../runbooks/ansible-operations.md).
+- Login/MFA state: SSO login disabled 2026-08-08; local accounts
+  (`windy`, `zhiqiangf`) use local passwords, no MFA. `unifi-network-mcp`
+  works for read and write operations. See
+  [docs/unifi-network.md](../docs/unifi-network.md).

runbooks/ansible-operations.md

@@ -59,3 +59,26 @@ ansible-playbook playbooks/maintenance-preview.yml
 # Baseline observations; logrotate management remains opt-in
 ansible-playbook playbooks/baseline.yml
 ```
+
+## UniFi SSO login setting (mutating)
+
+Reconciles `super_sdn.sso_login_enabled` on the UniFi controller (host `ubnt`,
+group `unifi`). Idempotent and gated: without `unifi_sso_confirm=true` the
+playbook only reports the current state and refuses to change anything.
+
+```bash
+# Read-only status report
+ansible-playbook playbooks/unifi-sso.yml --limit unifi --check
+
+# Apply (disable SSO login; local accounts use local passwords, no MFA)
+ansible-playbook playbooks/unifi-sso.yml --limit unifi \
+  -e '{"unifi_sso_confirm": true, "unifi_sso_target_value": false}'
+
+# Rollback (re-enable SSO login)
+ansible-playbook playbooks/unifi-sso.yml --limit unifi \
+  -e '{"unifi_sso_confirm": true, "unifi_sso_target_value": true}'
+```
+
+The controller container is not restarted by default; the UI path applies the
+setting immediately. Set `unifi_sso_restart_controller: true` only when the
+setting was changed directly in the DB while the controller was running.