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
This commit is contained in:
Joseph Doherty
2026-11-17 11:45:51 -05:00
parent 1d2170a152
commit a5243b1e87
4 changed files with 9 additions and 6 deletions
+6 -3
View File
@@ -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 <jwt>` 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.