2 Commits

Author	SHA1	Message	Date
Julien Gautier	f50d2d66c0	feat(portal-bff): distinct admin session + /api/admin/auth flow ... Phase-3a step per ADR-0020 §"Sessions — distinct from `portal-shell`". Wires a second `express-session` middleware on `/api/admin/*` carrying `__Host-portal_admin_session` over Redis prefix `session:admin:` and ships the parallel `/api/admin/auth/{login,callback,me,logout}` flow that populates it. Signing in to one surface no longer signs the user into the other — Entra SSO at the IdP level still preserves the click-through experience. What lands - `session/admin-session-cookie.ts`: `adminSessionCookieName()` mirrors the existing user-portal pattern (`__Host-` prefix in prod, plain name in dev). - `SessionModule` provides two parallel `express-session` instances via a shared `buildSessionMiddleware()` factory: SESSION_MIDDLEWARE cookie portal_session prefix session: ADMIN_SESSION_MIDDLEWARE cookie portal_admin_session prefix session:admin: The TTL policy, encryption key, signing secret, and session-id entropy are unchanged — only the cookie name + Redis key prefix differ. - `main.ts` mounts a tiny path-routed dispatch: requests under `/api/admin` get the admin session, everything else gets the user one. Running both middlewares unconditionally would have the second overwrite `req.session` from the first, collapsing the two surfaces. - `EntraConfig` gains `adminRedirectUri` + `adminPostLogoutRedirectUri`, validated at boot. The validator refuses to start when admin and user redirect URIs collide (would silently fuse the two surfaces). Both URIs must be registered on the same Entra app registration. - `AuthService.{beginAuthCodeFlow,completeAuthCodeFlow,buildLogoutUrl}` now take their redirect / post-logout URI as a parameter. Callers pick which set to pass. - New shared service `SessionEstablisher`: establish(user, req, res, surface) — full sign-in recipe: mint CSRF, populate session fields, save, register in user_sessions index, emit auth.sign_in audit, log. destroy(actor | undefined, req) — sign-out recipe: when actor is set, remove from index + emit auth.sign_out audit; always destroy the session (with Redis-hiccup tolerance). Both `AuthController` and the new `AdminAuthController` call it — no duplication of the 150-LOC session lifecycle logic. - `AdminAuthController` mounts `/api/admin/auth/{login,callback,me,logout}`. Structurally identical to `AuthController` but passes `adminRedirectUri` / `adminPostLogoutRedirectUri` and clears the admin session cookie on logout. `me` exposes the `roles` claim (the SPA needs it for conditional admin UI); the user-portal `me` intentionally still doesn't. New env vars (mandatory at boot) - ENTRA_ADMIN_REDIRECT_URI - ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI Tests: +25 specs (admin cookie 3, session-establisher 11, admin auth controller 9, entra config 2). Existing AuthController tests preserved through the refactor by passing a real `SessionEstablisher` constructed with the same audit / index / logger mocks.	2026-05-14 02:00:54 +02:00
julien	58e3b65bd9	feat(portal-bff): entra config foundation — boot validator + auth module (#102) ... ## Summary First step of ADR-0009 wiring on the BFF: capture the Entra app-registration env vars in the boot pipeline so subsequent PRs can plug `@azure/msal-node` onto a typed, already-validated config without re-reading `process.env`. **No MSAL client, no OIDC routes, no session integration yet** — those land in follow-up PRs. ## What lands - **[`.env.example`](apps/portal-bff/.env.example)** promotes the Entra block from its previous "future-vars" comment stub to an active section. Six keys: - `ENTRA_INSTANCE_URL` — the Microsoft login endpoint (e.g. `https://login.microsoftonline.com/`). - `ENTRA_TENANT_ID`, `ENTRA_CLIENT_ID`, `ENTRA_CLIENT_SECRET` — the values from the Entra app-registration UI. - `ENTRA_REDIRECT_URI`, `ENTRA_POST_LOGOUT_REDIRECT_URI` — consumed by the OIDC routes in a follow-up PR. Multi-tenant `ENTRA_ACCEPTED_TENANT_IDS` stays in the future-vars comment until External ID activation (ADR-0008 phase 2). - **[`apps/portal-bff/src/config/check-entra-config.ts`](apps/portal-bff/src/config/check-entra-config.ts)** — boot-time validator mirroring `check-database-url.ts`. Verifies every required key is present, the instance URL is `https://` and ends with `/`, tenant + client IDs are UUIDs, none of them are the literal placeholder values from `.env.example`, and the two redirect URIs parse as URLs. Returns a typed `EntraConfig` object with a pre-computed `authority` field (`${instanceUrl}${tenantId}`) so the future MSAL factory does not re-derive it. - **[`auth.module.ts`](apps/portal-bff/src/auth/auth.module.ts)** — `AuthModule` whose v1 surface is one provider: the parsed `EntraConfig` keyed by the `ENTRA_CONFIG` injection token. Factory delegates to `assertEntraConfig()`. Non-global on purpose — consumers state intent by importing the module. - **Bootstrap wiring** — `main.ts` calls `assertEntraConfig()` alongside `assertDatabaseUrl()` so misconfiguration fails fast at boot rather than mid-request (per ADR-0018 §"BFF env-var loading"). `AppModule` imports `AuthModule`. ## Naming choice Chose `ENTRA_*` rather than `AZURE_AD_*` to align with the ADR text (Microsoft Entra ID, post-2023 rebrand). The values you copy from the Entra app-registration UI go into `apps/portal-bff/.env` (git-ignored). ## Decisions worth flagging - **Validator called twice** — once in `main.ts` (boot-time fail-fast) and once in the `AuthModule` factory (to obtain the value for DI). Both reads are idempotent and trivially cheap. The duplication is intentional: boot-time gives a clear, pre-NestFactory error; the factory call surfaces the typed value to consumers. - **No `@azure/msal-node` dependency added yet** — introducing the dep without a consumer would be a smell. Lands in the next PR alongside the MSAL client factory. - **Pre-computed `authority`** in the parsed config rather than letting each MSAL consumer concatenate `instanceUrl + tenantId`. One place to change if the multi-tenant authority (`/organizations`, `/common`) replaces the tenant-scoped one when External ID activates. ## Verification - `nx run-many -t lint test build --projects=portal-bff` — green. - **29 / 29 specs** (was 20; +9 from the new entra-config spec + auth.module spec). - Boot smoke test (manual): with the placeholder values in `.env.example`, `nx serve portal-bff` aborts immediately with `ENTRA_CLIENT_ID is still the .env.example placeholder (…)`. With real values in a local `.env`, the BFF starts normally. ## Test plan - [x] Lint + test + build green. - [x] Validator unit-test covers happy path + every documented failure mode. - [ ] Manual: drop the real Entra values you obtained into `apps/portal-bff/.env`, `nx serve portal-bff` boots clean. - [ ] Manual: temporarily blank out one of the four `ENTRA_*` keys → BFF aborts at boot with a clear message naming the missing key. ## Next PRs on the auth track 1. Install `@azure/msal-node`, add the `MsalConfidentialClient` factory provider in `AuthModule`, expose it via DI. 2. First OIDC routes: `/api/auth/login` (PKCE-initiated redirect to Entra) + `/api/auth/callback` (token exchange + ID-token validation, audit-logged, no session persistence yet). 3. Session persistence per ADR-0010 (Redis + AES-GCM, `__Host-portal_session` cookie). Closes the auth loop. 4. RP-initiated logout, CSRF protection, route guards. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #102	2026-05-12 02:27:55 +02:00