docs(glauth): LDAPS trust options, ldapwhoami gotcha, windev mxgw on :3894 (mxaccessgw#180)

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
Joseph Doherty
2026-11-13 02:42:32 -05:00
parent 53013eb2d8
commit 127f07e1ef
+26
View File
@@ -26,6 +26,32 @@ LDAPS runs next to plain LDAP; `:3893` is unchanged, so every existing `Transpor
- **Rotating:** generate a new pair in `~/zb-glauth/tls/` on the host, copy `cert.pem` back here, update
the thumbprint above, `docker compose up -d --force-recreate`. Pinning clients should carry old + new
thumbprints across the swap.
- **Trusting it:** the cert is self-signed with `CA:TRUE`, so it is its own trust anchor. There are two
ways to trust it:
1. **Pin it (preferred).** Some clients can pin the server certificate, for example mxaccessgw's
`MxGateway:Ldap:ServerCertificateThumbprintSha256`. Pin the SHA-256 thumbprint above; nothing goes
into a trust store.
2. **Install it as a root.** Otherwise add `tls/cert.pem` to the client's trusted roots: on Windows
`Import-Certificate -FilePath cert.pem -CertStoreLocation Cert:\LocalMachine\Root`; on Linux,
copy it into `/usr/local/share/ca-certificates/zb-shared-glauth.crt` and run `update-ca-certificates`;
in a container, `LDAPTLS_CACERT`.
The cert's SAN covers `10.100.0.35`, so connect by IP (or `zb-shared-glauth` on a docker network).
- **StartTLS on `:3893`:** not enabled. LDAPS on its own port leaves every plaintext client untouched,
so it is the safe default.
- **`ldapwhoami` gotcha:** GLAuth has no WhoAmI extended operation, so `ldapwhoami` reports
`Protocol error (2)` even when the bind succeeded. Test binds with `ldapsearch`. A good user bind shows
`Insufficient access (50)`; a bad password shows `Invalid credentials (49)`.
- **Consumers on LDAPS:**
- **windev's MxAccessGw** (`10.100.0.48`) since 2026-11-13. It runs as `Production` with
`Transport=Ldaps`, `Port=3894` and the thumbprint pinned (mxaccessgw#180).
- Verified that day:
- `openssl s_client -verify_ip` returned `0 (ok)`.
- `ldapsearch` over `ldaps://…:3894` returned 50 for `multi-role`/`password` and 49 for a bad password.
- The gateway's `POST /auth/login` returned 302 to `/` for `multi-role`.
- The host's conntrack showed windev's binds only on `dport=3894`.
- Plain `:3893` still returned 50 for a good bind.
- Every other consumer (the local OtOpcUa, ScadaBridge, HistorianGateway and ignitionoee stacks)
still uses plain `:3893`.
- **Not covered:** the redundant local pair (`zb-ldap-primary`/`zb-ldap-backup` on the Mac) and each
wonder box's own `ScadaBridge-LDAP` GLAuth remain plain-only.