ScadaBridge/docs/plans/2026-06-16-disable-login-design.md

Disable-Login (Dev Auto-Login) Flag — Design

Date: 2026-06-16 Status: Approved (design); implementation plan to follow. Branch: feature/disable-login (off main, which now contains the merged M2 work).

Goal

Port the sister project OtOpcUa's "disable login" config flag to ScadaBridge: a dev/test flag that, when enabled, bypasses the login form entirely and auto-authenticates every request as the multi-role user with all ScadaBridge roles (full permissions, system-wide / all sites). Default OFF.

Scope decisions (confirmed with user)

• Safety guarding: Faithful copy of OtOpcUa — no environment guard. The flag works in any ASPNETCORE_ENVIRONMENT; the only protection is a loud LogWarning on startup. (Noted risk: unlike OtOpcUa's AdminUI, this disables authentication on a SCADA control surface — the warning wording is emphatic and the doc-comment says "never enable in production." No code guard, by explicit choice.)
• Workflow: the completed M2 (Tier-2) work was merged to main first (b2d8fd8); this feature is built on feature/disable-login off that updated main, so it can reuse M2.19's SessionClaimBuilder.
• Mechanism: a custom ASP.NET Core AuthenticationHandler registered under the cookie scheme name when the flag is set (OtOpcUa's exact mechanism) — not request-middleware, not a Blazor AuthenticationStateProvider override.

Reference: how OtOpcUa does it

(Verified read-only against /Users/dohertj2/Desktop/OtOpcUa.)

• Config key Security:Auth:DisableLogin (bool) + Security:Auth:User (string, default "multi-role-test"), bound to AuthDisableLoginOptions (SectionName = "Security:Auth").
• AutoLoginAuthenticationHandler — HandleAuthenticateAsync mints a ClaimsPrincipal with Name/Username/DisplayName + one Role claim per DevAuthRoles.All (all enum role names
  • "Operator"), returns AuthenticateResult.Success. No cookie written — every request re-authenticates fresh. SignInAsync/SignOutAsync are explicit no-ops (required, because /auth/logout calls HttpContext.SignOutAsync() on the scheme; without the no-ops the framework throws casting the handler to a sign-out handler).
• Wiring (startup): reads the flag; if true, AddAuthentication(Cookies) then .AddScheme<AuthenticationSchemeOptions, AutoLoginAuthenticationHandler>(Cookies, _ => {}) instead of .AddCookie(...). Since every authorization policy names the cookie scheme, they all authenticate through the handler — zero policy changes.
• Safety: no environment guard; a PostConfigure<ILoggerFactory> emits one loud LogWarning naming the user + roles. The login page is not hidden — it is simply never reached because every request is already authenticated.

ScadaBridge adaptation

ScadaBridge has its own role vocabulary and (post-M2.19) a canonical claim builder; the port adapts to both.

1. Config / options

New AuthDisableLoginOptions in ZB.MOM.WW.ScadaBridge.Security:

public sealed class AuthDisableLoginOptions
{
    public const string SectionName = "ScadaBridge:Security:Auth";
    public bool DisableLogin { get; set; }                 // default false
    public string User { get; set; } = "multi-role";       // canonical ScadaBridge test user
}

appsettings.json ships with the section absent or "DisableLogin": false. The flag is only set true in local/dev configs (e.g. a docker-dev env var ScadaBridge__Security__Auth__DisableLogin=true).

2. Roles — single source of truth

ScadaBridge declares exactly four roles in Roles.cs: Administrator, Designer, Deployer, Viewer. Add a Roles.All array (mirrors OtOpcUa's DevAuthRoles.All) so "all permissions" stays in sync if a role is added:

public static readonly string[] All = [Administrator, Designer, Deployer, Viewer];

3. Auto-login handler

AutoLoginAuthenticationHandler in ZB.MOM.WW.ScadaBridge.Security, deriving from SignInAuthenticationHandler<AuthenticationSchemeOptions> (so it satisfies the sign-in/sign-out handler contract). It reuses M2.19's SessionClaimBuilder.Build(...) for claim parity with a real login:

var user = string.IsNullOrWhiteSpace(_opts.User) ? "multi-role" : _opts.User;
var mapping = new RoleMappingResult(Roles.All, [], IsSystemWideDeployment: true);
var principal = SessionClaimBuilder.Build(
    username: user, displayName: user, groups: [], mapping: mapping, refreshTimestamp: now);
return AuthenticateResult.Success(new AuthenticationTicket(principal, Scheme.Name));

This yields: Name/Username/DisplayName = the user; all four Role claims; no ScopeId claims (IsSystemWideDeployment: true ⇒ system-wide, all sites). The LastActivity/LastRoleRefresh stamps that SessionClaimBuilder adds are harmless here (the auto-login scheme has no OnValidatePrincipal, so M2.19's idle/refresh logic is simply bypassed — correct for a dev bypass). now comes from the injected TimeProvider.

SignInAsync and SignOutAsync are no-ops (so /auth/logout does not throw). _opts is the resolved AuthDisableLoginOptions.

4. Wiring

The scheme choice is build-time and config-coupled, mirroring how AddZbLdapAuth(configuration, …) is called at the Host root immediately before AddSecurity(). Thread the flag into AddSecurity (re-add a minimal parameter — the shape it had before the LDAP cutover, e.g. AddSecurity(this IServiceCollection services, bool disableLogin = false)):

• flag false (default): unchanged — AddAuthentication(Cookies).AddCookie(...) with the existing cookie hardening + M2.19 OnValidatePrincipal.
• flag true: AddAuthentication(Cookies).AddScheme<AuthenticationSchemeOptions, AutoLoginAuthenticationHandler>(Cookies, _ => {}) instead of AddCookie, and emit the loud startup LogWarning.

Program.cs (Host) reads ScadaBridge:Security:Auth:DisableLogin from builder.Configuration and passes it to AddSecurity(...). AddOptions<AuthDisableLoginOptions>().Bind(section) is registered so the handler can resolve User.

5. Safety (faithful copy — warning only)

No environment guard. One emphatic LogWarning at startup when the flag is on, e.g.:

"AUTH DISABLED (ScadaBridge:Security:Auth:DisableLogin=true) — every request is authenticated as '{User}' with FULL permissions ({Roles}) across ALL sites. This is a SCADA control surface; dev/test ONLY — never enable in production."

The AuthDisableLoginOptions doc-comment repeats "Default OFF. Never enable in production."

6. Unchanged

Login page, /auth/login, RoleMapper, LDAP (AddZbLdapAuth), cookie hardening, and the M2.19 cookie session validator are all untouched. In disable-login mode the login-redirect path is never reached because every request is pre-authenticated.

Error handling

• HandleAuthenticateAsync always returns success — it cannot fail (no I/O, no LDAP, no DB).
• No-op sign-in/out cannot throw.
• If User is blank, fall back to "multi-role".

Testing

xUnit, in ZB.MOM.WW.ScadaBridge.Security.Tests (mirroring the existing harness):

1. Handler — HandleAuthenticateAsync returns an authenticated principal whose identity name is the configured user, carries all four Roles.All role claims, and has no ScopeId claim (system-wide). A blank/whitespace User falls back to multi-role.
2. No-op sign-in/out — SignInAsync/SignOutAsync complete without throwing.
3. Registration switch — with the flag true the registered handler for the cookie scheme is AutoLoginAuthenticationHandler; with the flag false it is the cookie handler (assert via the resolved IAuthenticationSchemeProvider / scheme HandlerType).
4. (Optional) Claim parity — the handler's principal matches a real-login principal shape for an all-roles system-wide user (reuse the M2.19 SessionClaimBuilderParityTests idiom).

Files (anticipated)

• New: src/ZB.MOM.WW.ScadaBridge.Security/Auth/AuthDisableLoginOptions.cs, .../Auth/AutoLoginAuthenticationHandler.cs.
• Modify: src/ZB.MOM.WW.ScadaBridge.Security/Roles.cs (All array), .../ServiceCollectionExtensions.cs (flag param + scheme switch + warning + options bind), src/ZB.MOM.WW.ScadaBridge.Host/Program.cs (read flag, pass to AddSecurity).
• Tests: tests/ZB.MOM.WW.ScadaBridge.Security.Tests/AutoLoginAuthenticationHandlerTests.cs (+ a registration-switch test).
• Docs/deploy (optional): note the flag in the Security component doc / docker-dev appsettings.

Out of scope

• Any production safety guard (explicitly declined).
• Hiding/redirecting the login page (unnecessary — it is unreachable when auth always succeeds).
• Bearer-token (/auth/token) path — unaffected; this is the cookie/interactive path only.