ADR 0005: Identity model with a local development identity mode

Status

Accepted

Date

2026-09-13

Deciders

Founder, product team

Context

The reference profile signs users in with Microsoft Entra ID through MSAL (PKCE redirect, silent renewal through /auth/bridge) and validates RS256 v2 tokens in the API. No Entra tenant or app registration exists for Trovensa yet, and the release is deferred, so nothing in this run can complete a real sign-in. The web e2e suite skips cleanly without saved auth state, but screenshots and a browser pass with zero console errors still need a signed-in session locally.

Decision

• Production identity is unchanged from the profile: Entra ID, MSAL in the browser, /auth/bridge registered as a SPA redirect URI for http://localhost:3100 and https://console.trovensa.com, RS256 tokens with pinned issuer and audience in the API.
• A development identity mode exists on both sides. The API accepts HS256 tokens with header kid: dev signed with DEV_TOKEN_SECRET only when APP_ENV is dev or test; validate_deployed_secrets() refuses to start in staging or production with a dev secret. api/scripts/dev_token.py mints such tokens with a user, an organisation slug and persona keys.
• The web app uses MSAL when NEXT_PUBLIC_AUTH_CLIENT_ID is set; otherwise, and only in development builds, it sends NEXT_PUBLIC_DEV_TOKEN as the bearer token. The production image sets the client id and therefore never uses the dev path.
• Tenant = organisation; memberships, groups and role assignments live in the database, not in the identity provider.

Consequences

• Local shots and the browser pass run against http://localhost:3100 with a dev token and a seeded illustrative program.
• A test proves that dev tokens are rejected when app_env is prod.
• The first real release requires the Entra app registration and redirect URIs (runbook step in infra/RUNBOOK-first-release.md).

Alternatives considered

• Entra only, register an app now: blocks local verification on tenant administration; rejected for this run.
• A mock identity provider container: heavier than a signed dev token and adds a moving part; rejected.

Follow-ups

• Register the Entra application and record the client id and authority in the web build args before the first release.