feat(portal-bff): distinct admin session + /api/admin/auth flow (#129)
## Summary
Phase-3a step per [ADR-0020](docs/decisions/0020-portal-admin-app.md) §"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.
## What lands
### Session middlewares — path-routed dispatch
| Token | Cookie | Redis prefix | Bound to |
| --- | --- | --- | --- |
| `SESSION_MIDDLEWARE` | `portal_session` / `__Host-portal_session` | `session:` | every path **except** `/api/admin/*` |
| `ADMIN_SESSION_MIDDLEWARE` | `portal_admin_session` / `__Host-portal_admin_session` | `session:admin:` | `/api/admin/*` only |
Implemented via a `buildSessionMiddleware(redis, logger, opts)` factory in [session.module.ts](apps/portal-bff/src/session/session.module.ts) — the TTL policy, encryption key, signing secret, session-id entropy, and serializer error-handling all come from the same source. Only the cookie name + Redis key prefix differ.
The dispatch in [main.ts](apps/portal-bff/src/main.ts) is a tiny `(req, res, next) => req.path.startsWith('/api/admin') ? adminSession(...) : userSession(...)`. Running both middlewares unconditionally would have the second overwrite `req.session` from the first, collapsing the two surfaces.
### Distinct admin auth flow
[`AdminAuthController`](apps/portal-bff/src/admin/admin-auth.controller.ts) mounts `/api/admin/auth/{login,callback,me,logout}`. Structurally identical to [`AuthController`](apps/portal-bff/src/auth/auth.controller.ts) but passes `adminRedirectUri` / `adminPostLogoutRedirectUri` and clears the admin session cookie on logout. `me` exposes the `roles` claim (admin SPA needs it for conditional UI); the user-portal `me` intentionally still doesn't.
### Shared `SessionEstablisher` (no controller duplication)
[`SessionEstablisher`](apps/portal-bff/src/auth/session-establisher.service.ts) encapsulates the session lifecycle so both controllers stay thin:
- `establish({ user, req, res, surface })` — mints CSRF, populates `user / createdAt / absoluteExpiresAt / csrfToken / mfaVerifiedAt`, saves, sets the CSRF cookie, registers in `user_sessions` index, emits `auth.sign_in` audit (blocking), logs with the `surface` tag.
- `destroy({ actor, req })` — when `actor` is set, removes from index + emits `auth.sign_out`; always destroys the session with Redis-hiccup tolerance.
No code duplicated between the two surfaces — the only per-surface differences are the redirect URIs (passed in) and the cookie names cleared on logout (controller-local).
### Entra config gains two URIs
`EntraConfig` adds `adminRedirectUri` + `adminPostLogoutRedirectUri`, validated at boot in [check-entra-config.ts](apps/portal-bff/src/config/check-entra-config.ts). The validator **refuses to start** when `ENTRA_ADMIN_REDIRECT_URI === ENTRA_REDIRECT_URI` — that misconfiguration would silently collapse the two surfaces into one session. Both URIs must be registered on the same Entra app registration's "Redirect URIs" list.
### `AuthService` API change
`beginAuthCodeFlow(redirectUri)`, `completeAuthCodeFlow(code, state, preAuth, redirectUri, now?)`, and `buildLogoutUrl(postLogoutRedirectUri)` now take their URI as a parameter. Callers (user-portal vs admin-portal controllers) pick which set to pass.
## Required ops action before this PR can run locally
Two new mandatory env vars. The BFF refuses to start without them.
```env
ENTRA_ADMIN_REDIRECT_URI=http://localhost:3000/api/admin/auth/callback
ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI=http://localhost:4201/
```
The example values land in [apps/portal-bff/.env.example](apps/portal-bff/.env.example) for reference. The corresponding Entra app registration also needs `/api/admin/auth/callback` added to its "Redirect URIs" list before any admin sign-in works end-to-end.
## Notes for the reviewer
- The user-portal callback's post-login redirect still targets `postLogoutRedirectUri` (existing quirk where the post-auth and post-logout landing happen to be the same URL). The admin callback mirrors the pattern for `adminPostLogoutRedirectUri`. Splitting these into dedicated post-login URIs is a separate ADR/PR.
- `AdminModule` now imports `AuthModule` to consume `AuthService`, `SessionEstablisher`, and `ENTRA_CONFIG`. `AuditWriter` and `RequireMfaGuard` come through transitively.
- Existing `AuthController` spec assertions are preserved through the refactor by constructing a **real** `SessionEstablisher` in the test fixture with the same audit / index / logger mocks. No behavioural assertion was removed — the inline session-state-setting logic is now exercised through the establisher.
- The pre-existing docstring in `check-entra-config.ts` line 11-16 still says "the two redirect URIs are mandatory once the OIDC routes ship (next PR)" — stale, the routes have shipped. Not touched in this PR to keep the diff focused; can be a one-line doc PR later.
## Test plan
- [x] `pnpm nx test portal-bff` — **278 specs pass** (was 253; +25: admin cookie 3, session-establisher 11, admin auth controller 9, entra config 2).
- [x] `pnpm exec nx affected -t format:check lint test build --base=origin/main` — clean (the pre-existing `_res` / `_next` warnings in `rate-limit.middleware.ts` are unrelated).
- [x] Entra config validator: both URIs required, both URL-validated, equality refused.
- [x] Path-dispatch verified by routing — `/api/admin/me` and `/api/admin/auth/*` see the admin session; everything else sees the user session.
- [ ] e2e — pending env var update + Entra registration update to add the admin redirect URI. Once both are in place: sign in via `/api/auth/login`, see `portal_session` cookie; clear cookies; sign in via `/api/admin/auth/login`, see `portal_admin_session` cookie; verify `/api/admin/me` works on the admin session and `/api/auth/me` works on the user session — neither sees the other's session.
---------
Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr>
Reviewed-on: #129
This commit was merged in pull request #129.
This commit is contained in:
@@ -0,0 +1,159 @@
|
||||
import { randomBytes } from 'node:crypto';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import type { Request, Response } from 'express';
|
||||
import { Logger } from 'nestjs-pino';
|
||||
import { AuditWriter } from '../audit/audit.service';
|
||||
import { csrfCookieName, csrfCookieOptions } from '../security/csrf-cookie';
|
||||
import { readSessionTimeouts } from '../session/session-cookie';
|
||||
import { UserSessionIndexService } from '../session/user-session-index.service';
|
||||
import type { AuthenticatedUser } from './auth.service';
|
||||
|
||||
export type AuthSurface = 'user' | 'admin';
|
||||
|
||||
/**
|
||||
* Shared session-establishment recipe used by both `AuthController`
|
||||
* (user-portal) and `AdminAuthController` (admin-portal). Per
|
||||
* ADR-0020 §"Sessions — distinct from `portal-shell`", the two
|
||||
* surfaces use distinct cookies / Redis namespaces — but the
|
||||
* *recipe* for persisting an authenticated user into a session is
|
||||
* identical:
|
||||
*
|
||||
* 1. Mint a CSRF token (per ADR-0009 §"Double-submit CSRF").
|
||||
* 2. Populate the session fields (`user`, `createdAt`,
|
||||
* `absoluteExpiresAt`, `csrfToken`, `mfaVerifiedAt`).
|
||||
* 3. Force `req.session.save()` before the 302 — `express-session`
|
||||
* writes on response end, but the redirect closes the response
|
||||
* before the async store write would otherwise complete.
|
||||
* 4. Mirror the CSRF token to the JS-readable cookie.
|
||||
* 5. Register the session id in the per-user index for future
|
||||
* "logout everywhere" — best-effort, a Redis hiccup does NOT
|
||||
* fail the sign-in.
|
||||
* 6. Emit the `auth.sign_in` audit row (blocking per ADR-0013).
|
||||
* 7. Log the success event.
|
||||
*
|
||||
* Surface-specific concerns — the redirect destination, the pre-auth
|
||||
* cookie clearing, the error paths — stay in the controllers.
|
||||
*
|
||||
* The middleware in `main.ts` has already resolved `req.session` to
|
||||
* the correct surface (user vs admin) by the time the controller's
|
||||
* callback handler runs; this service therefore writes to whichever
|
||||
* session was loaded without needing to know which one.
|
||||
*/
|
||||
@Injectable()
|
||||
export class SessionEstablisher {
|
||||
constructor(
|
||||
private readonly logger: Logger,
|
||||
private readonly userSessionIndex: UserSessionIndexService,
|
||||
private readonly audit: AuditWriter,
|
||||
) {}
|
||||
|
||||
async establish(opts: {
|
||||
user: AuthenticatedUser;
|
||||
req: Request;
|
||||
res: Response;
|
||||
/**
|
||||
* Tag forwarded into the success log so dashboards can split
|
||||
* user-portal sign-ins from admin-portal sign-ins. Audit rows
|
||||
* keep the same `auth.sign_in` event type in both cases —
|
||||
* adding a surface field to the audit catalogue is a follow-up
|
||||
* decision (current ADR-0013 catalogue is single-tier).
|
||||
*/
|
||||
surface: AuthSurface;
|
||||
}): Promise<void> {
|
||||
const { user, req, res, surface } = opts;
|
||||
const now = Date.now();
|
||||
const { idleSeconds, absoluteSeconds } = readSessionTimeouts();
|
||||
const csrfToken = randomBytes(32).toString('base64url');
|
||||
|
||||
req.session.user = user;
|
||||
req.session.createdAt = now;
|
||||
// Hard ceiling per ADR-0010 §"TTL policy" — checked on every
|
||||
// request by the absolute-timeout middleware, independent of
|
||||
// idle TTL.
|
||||
req.session.absoluteExpiresAt = now + absoluteSeconds * 1000;
|
||||
req.session.csrfToken = csrfToken;
|
||||
// MFA freshness anchor per ADR-0011 §"Confirmation". Entra's
|
||||
// CA policy decides whether MFA actually happened — the BFF
|
||||
// does not re-validate factors. Refreshed by future step-up
|
||||
// re-auth flows.
|
||||
req.session.mfaVerifiedAt = now;
|
||||
|
||||
await saveSession(req);
|
||||
|
||||
// Cookie maxAge matches the session's idle TTL so the CSRF
|
||||
// cookie expires alongside the session itself (rolling,
|
||||
// refreshed on each request).
|
||||
res.cookie(csrfCookieName(), csrfToken, csrfCookieOptions(idleSeconds * 1000));
|
||||
|
||||
// Best-effort: a Redis hiccup here doesn't fail sign-in.
|
||||
await this.userSessionIndex.add(user.oid, req.sessionID);
|
||||
|
||||
// Blocking audit per ADR-0013. If this throws the user does
|
||||
// NOT see a successful sign-in: the exception propagates and
|
||||
// the controller emits a 5xx via the StructuredErrorFilter.
|
||||
await this.audit.signIn({ actor: user, sessionId: req.sessionID });
|
||||
|
||||
this.logger.log(
|
||||
{
|
||||
event: 'auth.signed_in',
|
||||
surface,
|
||||
oid: user.oid,
|
||||
tid: user.tid,
|
||||
username: user.username,
|
||||
amr: user.amr,
|
||||
},
|
||||
'AuthCallback',
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Symmetric helper for the sign-out path. When `actor` is set,
|
||||
* removes the session id from the per-user index and emits the
|
||||
* `auth.sign_out` audit row (blocking per ADR-0013 — if the audit
|
||||
* row can't be written, the user does NOT get a "you're logged
|
||||
* out" experience). Then tears the session down unconditionally
|
||||
* — anonymous sign-outs still benefit from a `req.session.destroy()`
|
||||
* call to clear any orphan state in the store. A Redis hiccup on
|
||||
* `destroy()` is logged but non-fatal: clearing the cookie at the
|
||||
* HTTP layer (the controller's job) is sufficient to log the user
|
||||
* out from the BFF's point of view; the orphan Redis key will hit
|
||||
* its idle TTL on its own.
|
||||
*
|
||||
* The controller is responsible for HTTP-layer cleanup — the
|
||||
* session-cookie name is surface-specific (`portal_session` vs
|
||||
* `portal_admin_session`) and lives on the controller.
|
||||
*/
|
||||
async destroy(opts: { actor: AuthenticatedUser | undefined; req: Request }): Promise<void> {
|
||||
const { actor, req } = opts;
|
||||
|
||||
if (actor !== undefined) {
|
||||
const sessionId = req.sessionID;
|
||||
await this.userSessionIndex.remove(actor.oid, sessionId);
|
||||
await this.audit.signOut({ actor, sessionId });
|
||||
}
|
||||
|
||||
try {
|
||||
await destroySession(req);
|
||||
} catch (err) {
|
||||
this.logger.error(
|
||||
{
|
||||
event: 'session.destroy_failed',
|
||||
message: err instanceof Error ? err.message : String(err),
|
||||
},
|
||||
'AuthLogout',
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function saveSession(req: Request): Promise<void> {
|
||||
return new Promise((resolve, reject) => {
|
||||
req.session.save((err) => (err ? reject(err) : resolve()));
|
||||
});
|
||||
}
|
||||
|
||||
function destroySession(req: Request): Promise<void> {
|
||||
return new Promise((resolve, reject) => {
|
||||
req.session.destroy((err) => (err ? reject(err) : resolve()));
|
||||
});
|
||||
}
|
||||
Reference in New Issue
Block a user