ADR 0001 — Authentication model#

Status: Accepted (Phase 0, 2026-07-03)

Context#

The legacy Cube 1.x uses ASP.NET Forms cookie authentication backed by AspnetUsers / AspnetMembership (classic ASP.NET Membership schema). We need a token-based scheme that works for browser SPAs, desktop clients, and service-to-service calls, and that can coexist with the legacy system during the migration.

Decision#

• Issue JWT access tokens signed with HS256 for development and lower environments; RS256 upgrade path via Jwt:SigningKey swap when a KMS-backed key is available.
• One central Auth API endpoint set under /api/v1/auth/ (login, me, permissions).
• Passwords are verified through IPasswordHasher:
  • $2* prefix → BCrypt (new users, cost factor 11).
  • Any other stored hash → treated as a legacy format; PasswordHasher.NeedsRehash returns true and the caller records a “rehash on next login” intent. Legacy verification is gated on FeatureFlags:UseLegacyPasswordHash so we can force cutover.
• Claims carried in the token:
  • sub, unique_name, jti (standard),
  • role (mapped from AspMnxGroup),
  • perm (module-level permissions).

Consequences#

• Refresh tokens are not in scope for Phase 0. Access token lifetime defaults to 60 min.
• Legacy password hash verification is a placeholder — the actual scheme (SHA1 base64, salted?) must be confirmed by inspecting an existing AspnetMembership row in staging before Phase 1.
• Role / permission population is stubbed to empty arrays in Phase 0; Phase 1 wires the real group → role / claim mapping.