docs: dashboard disable-login design + save session-resilience tasklist snapshot
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,141 @@
|
||||
# Dashboard "Disable Login" Dev Flag — Design
|
||||
|
||||
**Date:** 2026-06-16
|
||||
**Status:** Approved (brainstorming) — ready for implementation plan.
|
||||
|
||||
## Goal
|
||||
|
||||
A config flag that **disables login in the gateway dashboard**. When enabled, every
|
||||
request is auto-authenticated as a fixed dev user (default **`multi-role`**) holding
|
||||
**both** dashboard roles (`Administrator` + `Viewer`), so no login form, cookie, or LDAP
|
||||
bind is involved and the whole UI behaves as a signed-in multi-role admin. Default
|
||||
**off**. Mirrors the sister project OtOpcUa's `Security:Auth:DisableLogin` feature.
|
||||
|
||||
## Why / scope
|
||||
|
||||
Speeds up dashboard testing against the remote dev boxes (10.100.0.48, wonder) with no
|
||||
sign-in round-trip and no GLAuth dependency. Scope is the **dashboard cookie web surface
|
||||
only** — the gRPC API-key auth path (`authorization: Bearer mxgw_…`) and its scopes are a
|
||||
separate auth model and are **untouched**.
|
||||
|
||||
## Background (current dashboard auth, verified)
|
||||
|
||||
- Dashboard auth is a **single cookie scheme** `MxGateway.Dashboard` registered in
|
||||
`Dashboard/DashboardServiceCollectionExtensions.cs::AddGatewayDashboard`
|
||||
(`AddAuthentication("MxGateway.Dashboard").AddCookie(...)`), plus a bearer scheme
|
||||
`MxGateway.Dashboard.HubToken` (`HubTokenAuthenticationHandler`) for SignalR hubs.
|
||||
- Real login: `/login` → `DashboardAuthenticator.AuthenticateAsync` → shared
|
||||
`ILdapAuthService` bind/search → `IGroupRoleMapper<string>` → `CreatePrincipal` builds a
|
||||
`ClaimsPrincipal` (`ZbClaimTypes.Name`/`Username`/`DisplayName` + one `ZbClaimTypes.Role`
|
||||
per role + `LdapGroupClaimType` group claims; identity authType = the cookie scheme,
|
||||
nameType = `ZbClaimTypes.Name`, roleType = `ZbClaimTypes.Role`) → cookie sign-in.
|
||||
- Authorization: a custom `DashboardAuthorizationHandler` evaluates
|
||||
`DashboardAuthorizationRequirement`. Policies: `ViewerPolicy` (AnyDashboardRole),
|
||||
`AdminPolicy` (AdminOnly), `HubClientsPolicy` (cookie **or** hub-token scheme,
|
||||
AnyDashboardRole).
|
||||
- Roles: exactly two — `DashboardRoles.Admin` (`"Administrator"`) and
|
||||
`DashboardRoles.Viewer` (`"Viewer"`).
|
||||
- **Existing escapes (important):** `DashboardAuthorizationHandler` already short-circuits
|
||||
when `Authentication.Mode == Disabled` or when `Dashboard.AllowAnonymousLocalhost`
|
||||
(default **true**) and the request is loopback. **But both only `context.Succeed(...)`
|
||||
the authorization requirement — they do not mint an authenticated principal.** So
|
||||
`HttpContext.User.Identity.IsAuthenticated` stays false, `Identity.Name` is null, and
|
||||
role-gated `AuthorizeView` write affordances stay **hidden**. That is precisely why they
|
||||
do not deliver the "logged-in multi-role admin" experience this feature needs.
|
||||
|
||||
## Approach (chosen: always-authenticating handler under the cookie scheme name)
|
||||
|
||||
When the flag is **on**, **replace the `.AddCookie(...)` registration with a custom
|
||||
`AuthenticationHandler` registered under the *same* scheme name**
|
||||
(`DashboardAuthenticationDefaults.AuthenticationScheme` = `"MxGateway.Dashboard"`). Its
|
||||
`HandleAuthenticateAsync` **always returns `AuthenticateResult.Success`** with the fixed
|
||||
dev principal (configured username, both roles), shaped identically to what
|
||||
`DashboardAuthenticator.CreatePrincipal` produces. `UseAuthentication()` stamps that
|
||||
principal on `HttpContext.User` for **every** request.
|
||||
|
||||
Registering under the cookie scheme name (not a new name) is the load-bearing detail: the
|
||||
`ViewerPolicy`, `AdminPolicy`, and `HubClientsPolicy` all resolve through that scheme via
|
||||
`DashboardAuthorizationHandler`'s role check, so they pass with **no policy or page
|
||||
changes**. The HTTP pipeline (Razor pages, admin endpoints), the Blazor circuit
|
||||
(`AuthorizeView`, `[CascadingParameter] AuthenticationState`), and the SignalR hubs are
|
||||
all covered by the single `HttpContext.User` seam. Because the handler authenticates every
|
||||
request, the feature is inherently **global** (all clients, including remote browsers) —
|
||||
the agreed scope.
|
||||
|
||||
`SignInAsync`/`SignOutAsync` are no-ops (no cookie to write or clear; the next request
|
||||
re-authenticates through the handler).
|
||||
|
||||
**Alternatives rejected:** (2) mint the principal inside the existing
|
||||
`DashboardAuthorizationHandler` bypass branches — authorization runs after authentication,
|
||||
so `HttpContext.User` is set too late for the Blazor auth state, and two seams must agree
|
||||
(this is essentially today's half-feature); (3) a pipeline middleware plus a stubbed
|
||||
`AuthenticationStateProvider` — two components to keep in sync, and a page request still
|
||||
302s to `/login` unless `HttpContext.User` is also set.
|
||||
|
||||
## Components
|
||||
|
||||
### 1. Config surface — two new fields on `DashboardOptions` (`MxGateway:Dashboard:*`)
|
||||
- `DisableLogin` (bool, default **false**).
|
||||
- `AutoLoginUser` (string, default **`"multi-role"`** — this project's GLAuth
|
||||
Administrator test user). Used as `Name`/`Username`/`DisplayName` of the minted
|
||||
principal; blank falls back to `"multi-role"`.
|
||||
|
||||
"All permissions" = principal minted with **both** `DashboardRoles.Admin` and
|
||||
`DashboardRoles.Viewer`.
|
||||
|
||||
### 2. `DashboardAutoLoginAuthenticationHandler`
|
||||
`AuthenticationHandler<AuthenticationSchemeOptions>` implementing
|
||||
`IAuthenticationSignInHandler`. Mirrors OtOpcUa's `AutoLoginAuthenticationHandler`, adapted
|
||||
to this project's claim shape (`ZbClaimTypes.*`, `DashboardRoles.*`). Always `Success`;
|
||||
SignIn/SignOut no-ops.
|
||||
|
||||
### 3. Wiring in `AddGatewayDashboard`
|
||||
Read `MxGateway:Dashboard:DisableLogin` directly from `IConfiguration` at registration
|
||||
time (the same idiom OtOpcUa uses, since scheme registration precedes options binding).
|
||||
- On → `AddScheme<AuthenticationSchemeOptions, DashboardAutoLoginAuthenticationHandler>(
|
||||
"MxGateway.Dashboard", _ => {})` in place of `AddCookie`; the `HubToken` scheme stays
|
||||
registered unchanged.
|
||||
- Off → existing `AddCookie(...)` path unchanged.
|
||||
|
||||
### 4. Safety
|
||||
- Default **off**.
|
||||
- A **loud one-time startup `LogWarning`** ("DASHBOARD LOGIN DISABLED
|
||||
(MxGateway:Dashboard:DisableLogin=true) — every request authenticated as '{user}' with
|
||||
full permissions (Administrator, Viewer). Dev/test only; never enable in production.")
|
||||
via the same options `PostConfigure<ILoggerFactory>` idiom OtOpcUa uses.
|
||||
- The existing `AllowAnonymousLocalhost` / `Authentication.Mode == Disabled` escapes are
|
||||
left untouched — `DisableLogin` is orthogonal (it changes *authentication*, minting a
|
||||
principal, not authorization bypass); when it is on the authorization handler's normal
|
||||
role-check branch succeeds, so the bypass branches simply do not matter.
|
||||
|
||||
## Error handling / edge cases
|
||||
|
||||
- Blank `AutoLoginUser` → falls back to `"multi-role"` (handler never mints a nameless
|
||||
principal).
|
||||
- `/login` still renders when the flag is on but is pointless (the user is already
|
||||
authenticated); `POST /login`'s `SignInAsync` is a no-op. `/logout` is likewise a no-op.
|
||||
No redirect added (YAGNI).
|
||||
- No interaction with the gRPC API-key path — that auth is entirely separate.
|
||||
|
||||
## Testing
|
||||
|
||||
- **Handler unit test:** `HandleAuthenticateAsync` returns `Success`;
|
||||
`principal.Identity.IsAuthenticated`, `Identity.Name == AutoLoginUser`,
|
||||
`IsInRole("Administrator")` && `IsInRole("Viewer")`; blank-user fallback.
|
||||
- **Wiring / integration (`WebApplicationFactory`):** with `DisableLogin=true`, an
|
||||
`AdminPolicy`-gated endpoint returns 200 with **no** cookie, and a `/hubs/*` negotiate
|
||||
authorizes; the startup warning is emitted.
|
||||
- **Regression:** with the flag off (default), the real cookie handler is still registered
|
||||
and existing dashboard auth tests pass.
|
||||
|
||||
## Docs to update in the same change
|
||||
|
||||
- `docs/GatewayConfiguration.md` — new `MxGateway:Dashboard:DisableLogin` /
|
||||
`AutoLoginUser` options.
|
||||
- The dashboard design doc (`docs/GatewayDashboardDesign.md`).
|
||||
- The CLAUDE.md dashboard-auth note (alongside the `AllowAnonymousLocalhost` mention).
|
||||
|
||||
## Scope / verification
|
||||
|
||||
Gateway-server-side only (.NET 10, x64) — builds and tests entirely on macOS. No worker,
|
||||
no `.proto`, no client, no gRPC changes.
|
||||
Reference in New Issue
Block a user