docs(ldap): windev runs Production on the shared GLAuth's LDAPS :3894 (#180)
ci / java (push) Failing after 15m34s
ci / nightly-windev (push) Has been skipped
ci / portable (push) Failing after 21m32s
ci / windows-x86 (push) Failing after 21m47s

windev's MxAccessGw now runs DOTNET_/ASPNETCORE_ENVIRONMENT=Production, with
DisableLogin removed and MxGateway:Ldap on Transport=Ldaps, Port=3894,
AllowInsecure=false and the GLAuth cert pinned by SHA-256. Record the env
change and the rollback, and update the stale "GLAuth has no LDAPS" text.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
Joseph Doherty
2026-11-13 02:42:05 -05:00
parent 2cc0d57541
commit 3e004708d4
2 changed files with 20 additions and 12 deletions
+16 -8
View File
@@ -305,7 +305,7 @@ dev/test GLAuth posture (`glauth.md`), not a production posture.
| `MxGateway:Ldap:Enabled` | `true` | Enables LDAP-backed dashboard login. |
| `MxGateway:Ldap:Server` | `localhost` | LDAP server host. Dev points at the shared GLAuth instance (`10.100.0.35`). |
| `MxGateway:Ldap:Port` | `3893` | LDAP server port. Must be between `1` and `65535`. |
| `MxGateway:Ldap:Transport` | `None` | Connection transport: `None` (plaintext), `StartTls` (upgrade), or `Ldaps` (implicit TLS). The dev default is `None` because the shared GLAuth instance has LDAPS disabled and binds send cleartext. **Production hard-stop (SEC-06):** when the host runs in the `Production` environment, `Transport` must not be `None` — startup validation fails otherwise. Deployed hosts must set `Ldaps` or `StartTls`. |
| `MxGateway:Ldap:Transport` | `None` | Connection transport: `None` (plaintext), `StartTls` (upgrade), or `Ldaps` (implicit TLS). The dev default is `None` (plaintext, the shared GLAuth's `:3893` listener). The shared GLAuth also serves LDAPS on `:3894` (self-signed, since 2026-11-10); use that with `Ldaps` plus `ServerCertificateThumbprintSha256` — windev does since 2026-11-13. **Production hard-stop (SEC-06):** when the host runs in the `Production` environment, `Transport` must not be `None` — startup validation fails otherwise. Deployed hosts must set `Ldaps` or `StartTls`. |
| `MxGateway:Ldap:AllowInsecure` | `true` | Permits a plaintext bind. Must be `true` when `Transport` is `None`; set `false` (with `Ldaps`/`StartTls`) in production. |
| `MxGateway:Ldap:ServerCertificateThumbprintSha256` | *(empty)* | Pins the LDAP server certificate by its SHA-256 thumbprint (mxaccessgw#180), so `Ldaps`/`StartTls` works against a directory with a self-signed certificate (e.g. GLAuth) without installing that certificate in the OS trust store. Empty (the default) keeps default OS trust-store validation, unchanged. When set, the server certificate is accepted **if and only if** its thumbprint matches one of the pins: chain and name errors are ignored for a matching certificate, and a non-matching certificate is rejected even if it chains to a trusted root. Format: the hex SHA-256 of the DER certificate, case-, colon-, dash- and space-insensitive — paste the output of `openssl x509 -in cert.pem -noout -fingerprint -sha256` (drop the `sha256 Fingerprint=` prefix) or, for a live server, `openssl s_client -connect host:636 </dev/null 2>/dev/null \| openssl x509 -noout -fingerprint -sha256`. To carry old + new across a certificate rotation, give several pins as a comma/semicolon-separated string (`"AB:CD:…,12:34:…"`, env var `MxGateway__Ldap__ServerCertificateThumbprintSha256`) or as a JSON array (`MxGateway__Ldap__ServerCertificateThumbprintSha256__0`, `__1`, …). Startup validation rejects an entry that is not 64 hex characters after normalization, and rejects any pin combined with `Transport=None` (plaintext has no certificate to pin). Applies to every endpoint, including `FallbackServers`. Shown on the dashboard Settings page. |
| `MxGateway:Ldap:SearchBase` | `dc=zb,dc=local` | Search base DN. |
@@ -335,13 +335,21 @@ staging rig, e.g. one pointed at the plaintext shared GLAuth). A production-like
deployment must therefore run with the literal `Production` environment name for
the hard-stops to apply.
`windev` (`10.100.0.48`) is deliberately labelled `Staging` (its NSSM
`DOTNET_ENVIRONMENT` entry, set 2026-08-07) rather than left at the `Production`
default. It is the permissive rig the parenthesis above describes: it runs
`Dashboard:DisableLogin=true` and binds the shared GLAuth, which offers no TLS,
so a `Production` label would contradict its own configuration and both
hard-stops would refuse the boot. Label a host `Production` only when its
configuration can satisfy them.
`windev` (`10.100.0.48`) runs as `Production` since 2026-11-13 (mxaccessgw#180).
From 2026-08-07 until then it was deliberately labelled `Staging`, because it ran
`Dashboard:DisableLogin=true` against the shared GLAuth's plaintext listener and both
hard-stops would have refused a `Production` boot. Its NSSM `AppEnvironmentExtra` now sets
`DOTNET_ENVIRONMENT=Production` and `ASPNETCORE_ENVIRONMENT=Production`, and it drops
`MxGateway__Dashboard__DisableLogin`, so dashboard login is LDAP. It also sets
`MxGateway__Ldap__Port=3894`, `MxGateway__Ldap__Transport=Ldaps`,
`MxGateway__Ldap__AllowInsecure=false` and `MxGateway__Ldap__ServerCertificateThumbprintSha256`,
the pin of the shared GLAuth's self-signed certificate, which lives in
`scadaproj/infra/glauth/README.md`. Nothing goes into the OS trust store. The pre-change
service key and appsettings are backed up in `C:\publish\mxaccessgw-backup-20261113-mxgw180\`;
to roll back, run `reg import` on the `.reg` file and restart. The wonder boxes (vd03, vq03,
vq04) still run `Staging`: each binds its own plain-only loopback GLAuth, and vd03 runs
`DisableLogin=true`. Label a host `Production` only when its configuration can satisfy both
hard-stops.
## Secrets Master Key
+4 -4
View File
@@ -27,7 +27,7 @@ gw-specific role.
| Protocol | LDAP (unencrypted) |
| Host | **`10.100.0.35`** (shared docker host — ~~`localhost`~~ retired) |
| Port | `3893` |
| LDAPS | disabled in dev (`Transport=None`, `AllowInsecure=true`) |
| LDAPS | **`:3894`** since 2026-11-10 (self-signed; pin the SHA-256 thumbprint from `scadaproj/infra/glauth/README.md`). windev uses it as `Production` since 2026-11-13 (mxaccessgw#180). Local dev defaults stay on `:3893` (`Transport=None`, `AllowInsecure=true`). |
| Base DN | `dc=zb,dc=local` |
| Bind DN format | `cn={username},dc=zb,dc=local` |
| Service account DN | `cn=serviceaccount,dc=zb,dc=local` (password: `<service-account-password>`) |
@@ -370,9 +370,9 @@ add a `tokenGroups` query as an enhancement.
Directory. *(The retired per-box `C:\publish\glauth\glauth.cfg` has the same caveat.)*
- The 3-fail / 10-minute lockout is per source IP, not per user — a
shared NAT can lock out a whole office. Tunable in `[behaviors]`.
- LDAPS isn't enabled in dev; binding sends passwords cleartext on the
wire. The shared GLAuth listens only on the LAN (`10.100.0.35`); never
expose port 3893 externally without enabling TLS first.
- The plain `:3893` listener sends bind passwords in cleartext. The shared GLAuth
listens only on the LAN (`10.100.0.35`); never expose `:3893` externally. Use the
LDAPS listener on `:3894` for anything production-labelled.
- **Enabling LDAPS against GLAuth (self-signed cert).** GLAuth's `[ldaps]`
listener normally uses a self-signed certificate. Rather than installing it in
the gateway host's trust store, pin it: set `MxGateway:Ldap:Transport=Ldaps`,