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:
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user