From a5243b1e873dab01f95cb80b22c00c74cda38e62 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 17 Nov 2026 11:45:51 -0500 Subject: [PATCH] docs(security): no role, no login now covers the management/CLI surfaces (#145) Component-Security "No role, no login": replace the "HTTP Basic is not covered yet" note with the Basic and Bearer behaviour, the throttle and log details; bearer section notes a role-less token is refused. Component-CLI: a zero-role user sees the bad-password 401. Component-ManagementService: 401 covers it. CLAUDE.md Security & Auth bullet updated. Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8 --- CLAUDE.md | 2 +- docs/requirements/Component-CLI.md | 2 +- docs/requirements/Component-ManagementService.md | 2 +- docs/requirements/Component-Security.md | 9 ++++++--- 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a20a6c3d..d8f5f6bf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -195,7 +195,7 @@ spec for each is `docs/requirements/Component-.md`, and `README.md` carrie - Authentication: direct LDAP bind (username/password), no Kerberos/NTLM. LDAPS/StartTLS required. - Two session models: the **UI** uses an HttpOnly/Secure cookie carrying a data-protected claims ticket (no embedded JWT; shared Data Protection keys; 30-minute idle timeout, DB-only role re-map every 15 min); the **CLI/API** exchanges credentials once per invocation at `POST /auth/token` for a 15-minute HS256 **bearer** JWT (`JwtSigningKey`, >= 32 bytes, shared by both centrals; `management_bearer: true` capability flag; Basic stays as fallback). Bearer roles are authoritative until expiry (revocation lag <= `JwtExpiryMinutes`; rotating the key kills every token). Cookies are the correct transport for Blazor Server (SignalR circuits). Spec: `Component-Security.md`. - LDAP failure: new logins fail; active sessions continue with current roles. -- **No role, no login (ScadaBridge#144, 2026-11-17).** `/auth/login` and `/auth/token` refuse a bind whose groups map to zero roles (or whose role mapping throws) with the exact bad-password response + a throttle failure; the reason is logged server-side only. A cookie session whose refresh maps to zero roles is ended (`CookieSessionValidator` → Reject). HTTP Basic on the management surfaces is not covered yet (follow-up). Spec: `Component-Security.md` *No role, no login*. +- **No role, no login (ScadaBridge#144/#145, 2026-11-17).** `/auth/login` and `/auth/token` refuse a bind whose groups map to zero roles (or whose role mapping throws) with the exact bad-password response + a throttle failure; the reason is logged server-side only. A cookie session whose refresh maps to zero roles is ended (`CookieSessionValidator` → Reject). The management/CLI surfaces (`/management`, `/api/audit/*`, `/hubs/debug-stream`) refuse the same way in `ManagementAuthenticator` (ScadaBridge#145): a zero-role or mapper-fault Basic bind gets the bad-password 401 + a throttle failure, and a bearer token with no role claim gets the invalid-token 401. Spec: `Component-Security.md` *No role, no login*. - Load balancer in front of central UI; cookie-embedded JWT + shared Data Protection keys for failover transparency. - Two-person MxGateway secured writes (M7): two new global roles — `Operator` (initiates) + `Verifier` (approves) — added alongside the canonical `Administrator`/`Designer`/`Deployer`/`Viewer`, with `RequireOperator`/`RequireVerifier` policies. An Operator submits a secured write from the Central UI Secured Writes page (`/operations/secured-writes`); it stays a `Pending` `PendingSecuredWrite` row until a *distinct* Verifier approves it (no-self-approval enforced server-side in the ManagementActor, plus a compare-and-swap race guard). Approval relays a `WriteTagRequest` to the site MxGateway; MxGateway-protocol connections only; each lifecycle event (submit/approve/reject/execute) emits a best-effort `AuditChannel.SecuredWrite` / `AuditKind.SecuredWrite*` central-direct-write row sharing the row id as `CorrelationId`. (SecuredWrite audit rows stamp `SourceNode` via `ICentralAuditWriter`/`INodeIdentityProvider`.) Pending secured writes expire server-side after a configurable TTL (`ManagementServiceOptions.SecuredWritePendingTtl`, default 24 h): an overdue `Pending` row is CAS'd to `Expired` (never relayed) — enforced at approve/reject and swept opportunistically on list (arch-review S2, `AuditKind.SecuredWriteExpire`). - **Inbound API key store — per node by default, shared on central pairs (2026-09-02, register row 108).** The shared `ZB.MOM.WW.Auth.ApiKeys` library stores inbound keys in **SQLite per node** unless `ScadaBridge:InboundApi:ApiKeyStore:Provider=SqlServer`, which points both central nodes at the same `zbauth` schema in the configuration database (library `ZB.MOM.WW.Auth.ApiKeys.SqlServer` 0.3.0) — under `SqlServer`, create/revoke/rotate/scope changes are cluster-wide immediately; a node's existing SQLite file is imported once at boot (insert-where-absent, safe on both nodes of a pair) and renamed `*.imported`. Central pairs **MUST** run `Provider=SqlServer` — a clustered Central left on `Sqlite` boots fine but `StartupValidator` logs a Warning, because a failover otherwise 401s every inbound client until keys are re-issued on the survivor. Both docker rigs (`docker/`, `docker-env2/`) run `SqlServer`; QA (`vq03`/`vq04`) runs `SqlServer` for both inbound keys and secrets since 2026-10-22 (deployment record `2026-10-22-wonder-app-vq03-vq04-3808b49f.md`); DEV (`vd03`, single node — not production) is not switched. The boot import's `*.imported` rename needs the importer's pooled SQLite handle released first — Windows refuses to rename an open file (fixed `6ed6800b`; pre-fix Windows builds need the manual rename in the runbook). Design: `docs/plans/2026-09-02-inbound-api-key-shared-store-design.md`; runbook: `docs/operations/inbound-api-key-reissue.md` → *Central pairs*. diff --git a/docs/requirements/Component-CLI.md b/docs/requirements/Component-CLI.md index 1b6008fd..0a07e74f 100644 --- a/docs/requirements/Component-CLI.md +++ b/docs/requirements/Component-CLI.md @@ -547,7 +547,7 @@ file/stdin forms for any value that carries a key or password. - **Connection failure**: If the CLI cannot connect to the management URL (e.g., DNS failure, connection refused), it exits with code 1 and a descriptive error message. - **Command timeout**: Ordinary CLI commands use a 30-second client deadline. All instance/artifact/site deployment aliases defer the overall deadline to the server, retaining a bounded socket-connect timeout. Server Ask expiry returns HTTP 504; a client deadline is reported locally. Bundle and Flow Debugger commands retain their explicit timeout policies. -- **Authentication failure**: If the server returns HTTP 401 (LDAP bind failed at `/auth/token` or on a Basic call, or a bearer token that a fresh exchange could not replace), the CLI exits with code 1. +- **Authentication failure**: If the server returns HTTP 401 (LDAP bind failed at `/auth/token` or on a Basic call, or a bearer token that a fresh exchange could not replace), the CLI exits with code 1. A user whose directory groups map to no ScadaBridge role gets the same `401` "Invalid username or password." as a wrong password, from `/auth/token` and on a Basic call alike — the server does not reveal which it was (ScadaBridge#144/#145; `Component-Security.md` *No role, no login*). Check the user's group mappings when valid credentials are refused. - **Authorization failure**: If the server returns HTTP 403, the CLI exits with code 2. ## Dependencies diff --git a/docs/requirements/Component-ManagementService.md b/docs/requirements/Component-ManagementService.md index fe486a42..7fb8a9d4 100644 --- a/docs/requirements/Component-ManagementService.md +++ b/docs/requirements/Component-ManagementService.md @@ -65,7 +65,7 @@ Content-Type: application/json - `ManagementSuccess` → HTTP 200 with JSON body - `ManagementError` → HTTP 400 with `{ "error": "...", "code": "..." }` - `ManagementUnauthorized` → HTTP 403 with `{ "error": "...", "code": "UNAUTHORIZED" }` -- Authentication failure → HTTP 401 +- Authentication failure → HTTP 401 (including a caller whose groups map to no role, or a bearer token with no role claim — `Component-Security.md` *No role, no login*) - Actor timeout → HTTP 504 - Large request while another is in flight → HTTP 409 with `{ "error": "...", "code": "IMPORT_IN_PROGRESS" }` (see below) diff --git a/docs/requirements/Component-Security.md b/docs/requirements/Component-Security.md index b4513096..7e9270a6 100644 --- a/docs/requirements/Component-Security.md +++ b/docs/requirements/Component-Security.md @@ -32,7 +32,7 @@ Central cluster. Sites do not have user-facing interfaces and do not perform ind Set in a local or docker-dev environment via the environment variable `ScadaBridge__Security__Auth__DisableLogin=true`. Note that `ScadaBridge:Security:Auth` is a child sub-section nested inside `ScadaBridge:Security`. -## No role, no login (ScadaBridge#144) +## No role, no login (ScadaBridge#144, #145) A successful LDAP bind is **not** enough to sign in: the user's groups must map to **at least one** ScadaBridge role. This is the family standard (scadaproj NAM AD cutover plan §3.2), and it matters once the LDAP search base is domain-wide — without it, any directory user could sign in role-less and read the bare-`[Authorize]` pages (`/` and `/monitoring/health`). @@ -40,7 +40,10 @@ A successful LDAP bind is **not** enough to sign in: the user's groups must map - **Indistinguishable from a bad password.** The client gets exactly the bad-credentials response — `/auth/login` redirects to `/login?error=Invalid username or password.` with no session cookie; `/auth/token` answers `401` `{ error: "Invalid username or password.", code: "AUTH_FAILED" }` with no token. The refusal also **counts as a login-throttle failure**, so the throttle cannot be used to tell "right password, no role" from "wrong password". - **Logged server-side only.** Each refusal is logged at Warning (category `ZB.MOM.WW.ScadaBridge.CentralUI.Auth.AuthEndpoints`) with the endpoint, the username and the reason (no mapped role, with the group count; or the mapping exception). There is no login audit event in the Audit Log — sign-in success and failure are not audited today — so the log line is the record. - **Sessions end the same way.** A cookie session whose groups map to zero roles on a refresh is ended (see *Cookie session lifecycle*). -- **HTTP Basic is not covered yet.** `ManagementAuthenticator`'s Basic branch (`POST /management`, the audit REST endpoints, the debug-stream hub) still authenticates a zero-role bind. Role-gated commands deny it, but the read-only management queries that `ManagementActor.GetRequiredRoles` opens to *any authenticated user* answer it. Closing that is a follow-up to ScadaBridge#144. +- **The management/CLI surfaces refuse too (ScadaBridge#145).** `ManagementAuthenticator` is the only source of the caller's identity for `POST /management`, the audit REST endpoints (`/api/audit/*`) and the debug-stream hub (`/hubs/debug-stream`), so the rule is enforced once there and covers all three — including the read-only commands `ManagementActor.GetRequiredRoles` opens to *any authenticated user*, which a zero-role caller would otherwise reach. + - **HTTP Basic:** a bind whose groups map to zero roles, or whose role mapping throws, answers exactly what a bad password answers on that surface — `401` `{ error: "Invalid username or password.", code: "AUTH_FAILED" }` (the hub aborts the connection) — and counts as a login-throttle failure; a refusal no longer clears earlier failures the way a successful bind does. + - **Bearer:** a token with no role claim is refused with the invalid-token response, `401` `{ error: "Invalid or expired bearer token.", code: "AUTH_FAILED" }`. `/auth/token` no longer mints such a token, but one minted before the rule shipped stays signed and unexpired for up to `JwtExpiryMinutes`. Like every bearer failure it involves no LDAP bind, so it does not feed the login throttle. A bearer request performs no role mapping, so a mapper fault does not affect it. + - Each refusal is logged at Warning (category `ZB.MOM.WW.ScadaBridge.ManagementService.ManagementAuthenticator`) with the endpoint (request path), the username and the reason. - Under the dev/test `DisableLogin` flag none of this runs: the auto-login identity holds every role. ## Session Management @@ -55,7 +58,7 @@ A successful LDAP bind is **not** enough to sign in: the user's groups must map - `POST /auth/token` (form `username`/`password`) performs the LDAP bind (login-throttled), maps the groups to roles and site scope (zero roles, or a mapping fault, is refused as a bad password — *No role, no login* above), and returns a short-lived **HS256 JWT** signed with `SecurityOptions.JwtSigningKey`, shared by both central nodes: `{ access_token, token_type: "Bearer", expires_in, management_bearer: true, username, display_name, roles }`. - **JWT claims**: display name, username, roles, and for a site-scoped Deployer the permitted site IDs (no site claims = system-wide, the same normalisation the Basic path uses). Issuer and audience are both fixed to `scadabridge-central`. Lifetime is `JwtExpiryMinutes` (default **15**). - `ManagementAuthenticator` accepts `Authorization: Bearer ` alongside HTTP Basic on every CLI-facing surface: `POST /management`, the audit REST endpoints, and the debug-stream hub (`/hubs/debug-stream`, token in the `Authorization` header of the negotiate request and WebSocket upgrade). Validation checks the HS256 signature, issuer, audience and lifetime (30 s clock skew for node-to-node drift; `nbf` is back-dated by the same skew so a peer whose clock lags the issuer accepts a fresh token after failover); unsigned (`alg=none`) or other-algorithm tokens are rejected, and a failure is a plain `401 AUTH_FAILED` (no LDAP bind, so it does not feed the login throttle). The token is never logged. -- **Roles and scope inside a valid token are authoritative for its lifetime**: a bearer request performs no LDAP bind and no role re-map. A role revocation therefore reaches a bearer caller when its token expires (≤ `JwtExpiryMinutes`); rotating `JwtSigningKey` invalidates every outstanding token immediately. +- **Roles and scope inside a valid token are authoritative for its lifetime**: a bearer request performs no LDAP bind and no role re-map. A token that carries no role claim is refused (*No role, no login* above). A role revocation therefore reaches a bearer caller when its token expires (≤ `JwtExpiryMinutes`); rotating `JwtSigningKey` invalidates every outstanding token immediately. - The CLI exchanges credentials once per process, keeps the token in memory only, re-exchanges once on a `401`, and falls back to HTTP Basic when the server has no bearer support — see `Component-CLI.md`. HTTP Basic stays supported on every surface. - Under the dev/test `DisableLogin` flag `/auth/token` answers `404`: the management surfaces already authenticate every request as the dev user, and no credential-free token is minted that another deployment sharing the key might honour. - **Signing key**: `StartupValidator` refuses to boot a Central node whose `JwtSigningKey` is missing or shorter than **32 UTF-8 bytes** (256 bits, the HMAC-SHA256 floor). `JwtTokenService` repeats the length check at construction as defence in depth.