From 3e004708d4bd099e95c55871a1091fc73a05cfe4 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 13 Nov 2026 02:42:05 -0500 Subject: [PATCH] docs(ldap): windev runs Production on the shared GLAuth's LDAPS :3894 (#180) 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 --- docs/GatewayConfiguration.md | 24 ++++++++++++++++-------- glauth.md | 8 ++++---- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/GatewayConfiguration.md b/docs/GatewayConfiguration.md index c6271d1f..5b76d053 100644 --- a/docs/GatewayConfiguration.md +++ b/docs/GatewayConfiguration.md @@ -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 \| 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 diff --git a/glauth.md b/glauth.md index 94ef4e20..073ddbfd 100644 --- a/glauth.md +++ b/glauth.md @@ -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: ``) | @@ -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`,