# Authentication experience audit

Reviewed on 31 August 2026 against the live unauthenticated routes and the Hub,
Fleet, and shared Entra integration code. No credentials, MFA challenges, or
customer Conditional Access policies were exercised.

## Current implementations

| Surface | Browser entry | Additional paths | Observed result |
|---|---|---|---|
| Customer/test Hub | Microsoft Entra | Session cookie, account switch, logout | Direct Microsoft redirect; no Hub-owned entry or result screen |
| Simulated Hub | HTTP Basic under `AUTH_MODE=dev` | Fixed development identity | Browser-native username/password dialog |
| Fleet | RapidCloud portal SSO | Emergency password, Basic for automation, Fleet session | Custom login; emergency password is collapsed |
| Kennisbank | Branded page followed by Entra | Account menu, switch, errors, logout | Complete app-owned journey around Microsoft-hosted identity screens |

The Kennisbank pattern demonstrates the right separation of responsibility, but
Hub copy and templates must be product/customer-specific rather than reused
verbatim.

## Findings

### Critical experience gaps

1. The simulated Hub can be mistaken for a customer preview even though its
   native Basic dialog is a development gate.
2. Hub callback cancellation currently returns raw JSON to the browser.
3. Other Hub callback failures also fall back to JSON when `ENTRA_LOGIN_PAGE`
   is not configured.
4. Hub logout uses generic embedded HTML containing incorrect Kennisbank copy.
5. Session expiry silently redirects without explaining the expiry or the route
   that will be restored.
6. The signed-in Hub identity is text rather than a complete account menu.

### Fleet hardening and clarity

1. SSO is correctly primary and the password is already visually secondary.
2. Emergency password use needs explicit rate limiting, CSRF protection,
   success/failure audit events, and alerts.
3. The Fleet session signature should use an independent signing secret rather
   than the emergency password.
4. Portal assertions should validate issuer and audience in addition to
   signature and expiry.
5. Native Basic must remain limited to non-browser compatibility traffic.

## Screen ownership

| State | Owner |
|---|---|
| Customer/Fleet introduction, session expiry, errors, forbidden account, logout, account menu | Hub or Fleet |
| Email/password entry, MFA, consent, Conditional Access, Microsoft account picker | Microsoft Entra |
| Development HTTP Basic dialog | Browser |

The Microsoft-hosted and browser-native dialogs cannot be styled by Hub or
Fleet. Product design controls the context before the redirect and the result
after it returns.

## Required release gate

- Configure a branded Hub login page through `ENTRA_LOGIN_PAGE`.
- Replace every browser JSON auth failure with a designed, non-sensitive state.
- Replace the generic logout fallback and test for product-name leakage.
- Preserve only allowlisted relative destinations through authentication.
- Provide account switch and logout from the signed-in account menu.
- Keep development Basic Auth off every customer and acceptance host.
- Add the Fleet emergency-access safeguards before treating it as production
  break-glass access.
- Complete end-to-end testing with dedicated allowed and forbidden Entra test
  accounts, including the customer's MFA and Conditional Access policies.