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

apps/portal-bff/.env.example

@@ -56,11 +56,20 @@ ENTRA_INSTANCE_URL=https://login.microsoftonline.com/
 ENTRA_TENANT_ID=00000000-0000-0000-0000-000000000000
 ENTRA_CLIENT_ID=00000000-0000-0000-0000-000000000000
 ENTRA_CLIENT_SECRET=replace_with_real_value
-# Redirect URIs registered in Entra alongside the same client id. Both
-# `/auth/callback` and `/auth/logout` paths are mounted by the BFF
-# once the OIDC routes land in a subsequent PR.
+# Redirect URIs registered in Entra alongside the same client id.
+# User portal — `/api/auth/callback` is the OIDC return URL; the
+# post-logout URL is where Entra sends the browser after RP-initiated
+# logout (typically the SPA landing page).
 ENTRA_REDIRECT_URI=http://localhost:3000/api/auth/callback
 ENTRA_POST_LOGOUT_REDIRECT_URI=http://localhost:4200/
+# Admin portal — distinct callback per ADR-0020 §"Sessions — distinct
+# from `portal-shell`" so Entra routes the response to the matching
+# session. Both `ENTRA_REDIRECT_URI` and `ENTRA_ADMIN_REDIRECT_URI`
+# must be registered in the same Entra app registration's
+# "Redirect URIs" list. Distinct post-logout URL routes admin
+# sign-outs to the admin SPA's landing page (port 4201 in dev).
+ENTRA_ADMIN_REDIRECT_URI=http://localhost:3000/api/admin/auth/callback
+ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI=http://localhost:4201/
 
 # Cookie signing secret (per ADR-0009 §"Cookies"). Used to sign the
 # transient pre-auth cookie that carries the OIDC `state` + PKCE

apps/portal-bff/src/admin/admin-auth.controller.spec.ts

@@ -0,0 +1,282 @@
+import type { Request, Response } from 'express';
+import type { Logger } from 'nestjs-pino';
+import type { AuditWriter } from '../audit/audit.service';
+import { PRE_AUTH_COOKIE_NAME } from '../auth/auth.cookie';
+import { AuthCodeFlowException } from '../auth/auth.errors';
+import type { AuthService, PreAuthPayload } from '../auth/auth.service';
+import type { EntraConfig } from '../auth/entra-config.token';
+import type { SessionEstablisher } from '../auth/session-establisher.service';
+import { AdminAuthController } from './admin-auth.controller';
+
+const ENTRA: EntraConfig = {
+  instanceUrl: 'https://login.microsoftonline.com/',
+  tenantId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+  clientId: '11111111-2222-3333-4444-555555555555',
+  clientSecret: 's3cret',
+  redirectUri: 'http://localhost:3000/api/auth/callback',
+  postLogoutRedirectUri: 'http://localhost:4200/',
+  adminRedirectUri: 'http://localhost:3000/api/admin/auth/callback',
+  adminPostLogoutRedirectUri: 'http://localhost:4201/',
+  authority: 'https://login.microsoftonline.com/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+};
+
+const USER = {
+  oid: 'admin-oid',
+  tid: ENTRA.tenantId,
+  username: 'admin@apf.example',
+  displayName: 'Admin Smith',
+  amr: ['pwd', 'mfa'],
+  roles: ['admin'],
+};
+
+const PRE_AUTH: PreAuthPayload = {
+  state: 'state-nonce',
+  codeVerifier: 'verifier-secret',
+  createdAt: 1_000,
+};
+
+const ADMIN_LOGOUT_URL = `${ENTRA.authority}/oauth2/v2.0/logout?post_logout_redirect_uri=${encodeURIComponent(ENTRA.adminPostLogoutRedirectUri)}`;
+
+function makeResStub() {
+  const res = {
+    cookie: jest.fn(),
+    clearCookie: jest.fn(),
+    redirect: jest.fn(),
+    status: jest.fn(),
+    json: jest.fn(),
+  };
+  res.cookie.mockReturnValue(res);
+  res.clearCookie.mockReturnValue(res);
+  res.redirect.mockReturnValue(res);
+  res.status.mockReturnValue(res);
+  res.json.mockReturnValue(res);
+  return res as unknown as Response & typeof res;
+}
+
+function makeReqStub(opts?: {
+  signedCookies?: Record<string, unknown>;
+  sessionUser?: typeof USER;
+}): Request {
+  return {
+    signedCookies: opts?.signedCookies ?? {},
+    session: opts?.sessionUser !== undefined ? { user: opts.sessionUser } : {},
+    sessionID: 'sid-admin',
+  } as unknown as Request;
+}
+
+function makeFixture(opts?: { completeAuthCodeFlow?: jest.Mock }) {
+  const beginAuthCodeFlow = jest.fn().mockResolvedValue({
+    authUrl: 'https://entra.example/authorize?state=state-nonce',
+    preAuthPayload: PRE_AUTH,
+  });
+  const completeAuthCodeFlow = opts?.completeAuthCodeFlow ?? jest.fn().mockResolvedValue(USER);
+  const buildLogoutUrl = jest.fn().mockReturnValue(ADMIN_LOGOUT_URL);
+  const authService = {
+    beginAuthCodeFlow,
+    completeAuthCodeFlow,
+    buildLogoutUrl,
+  } as unknown as AuthService;
+  const audit = {
+    signIn: jest.fn().mockResolvedValue(undefined),
+    signInFailed: jest.fn().mockResolvedValue(undefined),
+    signOut: jest.fn().mockResolvedValue(undefined),
+  };
+  const establisher = {
+    establish: jest.fn().mockResolvedValue(undefined),
+    destroy: jest.fn().mockResolvedValue(undefined),
+  };
+  const logger = { log: jest.fn(), warn: jest.fn(), error: jest.fn() };
+  return {
+    controller: new AdminAuthController(
+      authService,
+      logger as unknown as Logger,
+      ENTRA,
+      audit as unknown as AuditWriter,
+      establisher as unknown as SessionEstablisher,
+    ),
+    beginAuthCodeFlow,
+    completeAuthCodeFlow,
+    buildLogoutUrl,
+    audit,
+    establisher,
+    logger,
+  };
+}
+
+describe('AdminAuthController.login', () => {
+  it('passes the admin redirect URI to beginAuthCodeFlow', async () => {
+    const { controller, beginAuthCodeFlow } = makeFixture();
+    await controller.login(makeResStub());
+    expect(beginAuthCodeFlow).toHaveBeenCalledWith(ENTRA.adminRedirectUri);
+  });
+
+  it('writes the pre-auth cookie and 302s to the Entra auth URL', async () => {
+    const { controller } = makeFixture();
+    const res = makeResStub();
+    await controller.login(res);
+    expect(res.cookie).toHaveBeenCalledWith(
+      PRE_AUTH_COOKIE_NAME,
+      expect.any(String),
+      expect.objectContaining({ signed: true, httpOnly: true }),
+    );
+    expect(res.redirect).toHaveBeenCalledWith(302, expect.stringContaining('entra.example'));
+  });
+});
+
+describe('AdminAuthController.callback', () => {
+  it('passes the admin redirect URI to completeAuthCodeFlow and establishes a surface=admin session', async () => {
+    const { controller, completeAuthCodeFlow, establisher } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub({
+      signedCookies: { [PRE_AUTH_COOKIE_NAME]: JSON.stringify(PRE_AUTH) },
+    });
+
+    await controller.callback(req, res, 'auth-code', PRE_AUTH.state);
+
+    expect(completeAuthCodeFlow).toHaveBeenCalledWith(
+      'auth-code',
+      PRE_AUTH.state,
+      PRE_AUTH,
+      ENTRA.adminRedirectUri,
+    );
+    expect(establisher.establish).toHaveBeenCalledWith({
+      user: USER,
+      req,
+      res,
+      surface: 'admin',
+    });
+    expect(res.redirect).toHaveBeenCalledWith(302, ENTRA.adminPostLogoutRedirectUri);
+  });
+
+  it('redirects with ?auth_error=token-exchange-failed when Entra returns error', async () => {
+    const { controller } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub({
+      signedCookies: { [PRE_AUTH_COOKIE_NAME]: JSON.stringify(PRE_AUTH) },
+    });
+
+    await controller.callback(req, res, undefined, undefined, 'access_denied', 'consent declined');
+
+    expect(res.redirect).toHaveBeenCalledWith(
+      302,
+      expect.stringContaining('auth_error=token-exchange-failed'),
+    );
+    // Error redirect lands on the admin post-logout target, not the user-portal one.
+    expect(res.redirect).toHaveBeenCalledWith(
+      302,
+      expect.stringContaining(ENTRA.adminPostLogoutRedirectUri),
+    );
+  });
+
+  it('redirects with ?auth_error=flow-expired when the pre-auth cookie is missing', async () => {
+    const { controller, audit } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub({ signedCookies: {} });
+
+    await controller.callback(req, res, 'auth-code', PRE_AUTH.state);
+
+    expect(res.redirect).toHaveBeenCalledWith(
+      302,
+      expect.stringContaining('auth_error=flow-expired'),
+    );
+    expect(audit.signInFailed).toHaveBeenCalledWith(
+      expect.objectContaining({
+        failureKind: 'no-pre-auth-cookie',
+        payload: expect.objectContaining({ surface: 'admin' }),
+      }),
+    );
+  });
+
+  it('redirects with the typed error from AuthCodeFlowException', async () => {
+    const completeAuthCodeFlow = jest
+      .fn()
+      .mockRejectedValue(new AuthCodeFlowException({ kind: 'state-mismatch' }));
+    const { controller, audit } = makeFixture({ completeAuthCodeFlow });
+    const res = makeResStub();
+    const req = makeReqStub({
+      signedCookies: { [PRE_AUTH_COOKIE_NAME]: JSON.stringify(PRE_AUTH) },
+    });
+
+    await controller.callback(req, res, 'auth-code', PRE_AUTH.state);
+
+    expect(res.redirect).toHaveBeenCalledWith(
+      302,
+      expect.stringContaining('auth_error=state-mismatch'),
+    );
+    expect(audit.signInFailed).toHaveBeenCalledWith(
+      expect.objectContaining({
+        failureKind: 'state-mismatch',
+        payload: expect.objectContaining({ surface: 'admin' }),
+      }),
+    );
+  });
+});
+
+describe('AdminAuthController.me', () => {
+  it('returns the public payload with roles when the admin session is populated', () => {
+    const { controller } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub({ sessionUser: USER });
+    controller.me(req, res);
+    expect(res.json).toHaveBeenCalledWith({
+      oid: USER.oid,
+      tid: USER.tid,
+      username: USER.username,
+      displayName: USER.displayName,
+      roles: USER.roles,
+    });
+  });
+
+  it('throws UnauthorizedException when no user is on the admin session', () => {
+    const { controller } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub();
+    expect(() => controller.me(req, res)).toThrow(/Unauthenticated/);
+  });
+});
+
+describe('AdminAuthController.logout', () => {
+  it('destroys the admin session, clears the admin cookie + CSRF cookie, redirects to Entra logout', async () => {
+    const { controller, establisher, buildLogoutUrl } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub({ sessionUser: USER });
+
+    await controller.logout(req, res);
+
+    expect(establisher.destroy).toHaveBeenCalledWith({ actor: USER, req });
+    expect(buildLogoutUrl).toHaveBeenCalledWith(ENTRA.adminPostLogoutRedirectUri);
+    expect(res.clearCookie).toHaveBeenCalledWith('portal_admin_session', { path: '/' });
+    expect(res.clearCookie).toHaveBeenCalledWith('portal_csrf', { path: '/' });
+    expect(res.redirect).toHaveBeenCalledWith(302, ADMIN_LOGOUT_URL);
+  });
+
+  it('uses the __Host- prefixed admin cookie name in production', async () => {
+    const originalNodeEnv = process.env['NODE_ENV'];
+    try {
+      process.env['NODE_ENV'] = 'production';
+      const { controller } = makeFixture();
+      const res = makeResStub();
+      const req = makeReqStub({ sessionUser: USER });
+      await controller.logout(req, res);
+      expect(res.clearCookie).toHaveBeenCalledWith('__Host-portal_admin_session', {
+        path: '/',
+      });
+    } finally {
+      if (originalNodeEnv === undefined) {
+        delete process.env['NODE_ENV'];
+      } else {
+        process.env['NODE_ENV'] = originalNodeEnv;
+      }
+    }
+  });
+
+  it('still clears cookies and redirects for an anonymous admin sign-out', async () => {
+    const { controller, establisher } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub();
+    await controller.logout(req, res);
+    expect(establisher.destroy).toHaveBeenCalledWith({ actor: undefined, req });
+    expect(res.clearCookie).toHaveBeenCalledWith('portal_admin_session', { path: '/' });
+    expect(res.redirect).toHaveBeenCalled();
+  });
+});

apps/portal-bff/src/admin/admin-auth.controller.ts

@@ -0,0 +1,185 @@
+import { Controller, Get, Inject, Query, Req, Res, UnauthorizedException } from '@nestjs/common';
+import type { Request, Response } from 'express';
+import { Logger } from 'nestjs-pino';
+import { AuditWriter } from '../audit/audit.service';
+import {
+  PRE_AUTH_COOKIE_NAME,
+  clearPreAuthCookieOptions,
+  preAuthCookieOptions,
+} from '../auth/auth.cookie';
+import { AuthCodeFlowException, type AuthCodeFlowError, authErrorCode } from '../auth/auth.errors';
+import { AuthService, type PreAuthPayload } from '../auth/auth.service';
+import { ENTRA_CONFIG, type EntraConfig } from '../auth/entra-config.token';
+import { SessionEstablisher } from '../auth/session-establisher.service';
+import { csrfCookieName } from '../security/csrf-cookie';
+import { adminSessionCookieName } from '../session/admin-session-cookie';
+
+/**
+ * `/api/admin/auth/*` — admin-portal OIDC routes per ADR-0020.
+ *
+ * Structurally identical to the user-portal `AuthController`:
+ * `GET /login` 302s to Entra with PKCE + state in a signed cookie,
+ * `GET /callback` exchanges the code for tokens, establishes the
+ * admin session, and redirects to the admin SPA. `GET /me` reads
+ * the admin session back. `GET /logout` destroys the admin session
+ * and redirects to Entra's RP-initiated logout.
+ *
+ * The key difference is *which* `req.session` we're looking at: the
+ * session middleware mounted on `/api/admin/*` in `main.ts` resolves
+ * to the admin-session Redis namespace (`session:admin:*`) and uses
+ * the `__Host-portal_admin_session` cookie, distinct from
+ * `__Host-portal_session` used by the user portal. Per ADR-0020
+ * §"Sessions — distinct from `portal-shell`": signing in to one
+ * surface does NOT sign in to the other.
+ *
+ * Routes here are **deliberately not** guarded with `@RequireAdmin`
+ * or `@RequireMfa`. The whole point of the login flow is to *create*
+ * the session that those guards check against. Sub-controllers
+ * (admin business routes) layer the guards on top.
+ */
+@Controller('admin/auth')
+export class AdminAuthController {
+  constructor(
+    private readonly authService: AuthService,
+    private readonly logger: Logger,
+    @Inject(ENTRA_CONFIG) private readonly entra: EntraConfig,
+    private readonly audit: AuditWriter,
+    private readonly sessionEstablisher: SessionEstablisher,
+  ) {}
+
+  @Get('login')
+  async login(@Res() res: Response): Promise<void> {
+    const { authUrl, preAuthPayload } = await this.authService.beginAuthCodeFlow(
+      this.entra.adminRedirectUri,
+    );
+    res.cookie(PRE_AUTH_COOKIE_NAME, JSON.stringify(preAuthPayload), preAuthCookieOptions());
+    res.redirect(302, authUrl);
+  }
+
+  @Get('callback')
+  async callback(
+    @Req() req: Request,
+    @Res() res: Response,
+    @Query('code') code?: string,
+    @Query('state') state?: string,
+    @Query('error') entraError?: string,
+    @Query('error_description') entraErrorDescription?: string,
+  ): Promise<void> {
+    res.clearCookie(PRE_AUTH_COOKIE_NAME, clearPreAuthCookieOptions());
+
+    if (entraError) {
+      this.logger.warn(
+        {
+          event: 'auth.entra_error',
+          surface: 'admin',
+          entraError,
+          entraErrorDescription,
+        },
+        'AdminAuthCallback',
+      );
+      await this.audit.signInFailed({
+        failureKind: 'entra-error',
+        payload: { surface: 'admin', entraError, entraErrorDescription },
+      });
+      return this.redirectWithError(res, 'token-exchange-failed');
+    }
+
+    if (typeof code !== 'string' || typeof state !== 'string') {
+      await this.audit.signInFailed({
+        failureKind: 'missing-code-or-state',
+        payload: { surface: 'admin' },
+      });
+      return this.redirectWithError(res, 'token-exchange-failed');
+    }
+
+    const preAuth = readPreAuthCookie(req);
+    if (!preAuth) {
+      this.logger.warn({ event: 'auth.no_pre_auth_cookie', surface: 'admin' }, 'AdminAuthCallback');
+      await this.audit.signInFailed({
+        failureKind: 'no-pre-auth-cookie',
+        payload: { surface: 'admin' },
+      });
+      return this.redirectWithError(res, 'flow-expired');
+    }
+
+    try {
+      const user = await this.authService.completeAuthCodeFlow(
+        code,
+        state,
+        preAuth,
+        this.entra.adminRedirectUri,
+      );
+      await this.sessionEstablisher.establish({ user, req, res, surface: 'admin' });
+      res.redirect(302, this.entra.adminPostLogoutRedirectUri);
+    } catch (err) {
+      if (err instanceof AuthCodeFlowException) {
+        this.logger.warn(
+          { event: 'auth.flow_error', surface: 'admin', failure: err.failure },
+          'AdminAuthCallback',
+        );
+        await this.audit.signInFailed({
+          failureKind: err.failure.kind,
+          payload: { surface: 'admin' },
+        });
+        return this.redirectWithError(res, err.failure.kind);
+      }
+      throw err;
+    }
+  }
+
+  @Get('me')
+  me(@Req() req: Request, @Res() res: Response): void {
+    const user = req.session.user;
+    if (!user) {
+      throw new UnauthorizedException({
+        code: 'unauthenticated',
+        message: 'Unauthenticated',
+      });
+    }
+    res.json({
+      oid: user.oid,
+      tid: user.tid,
+      username: user.username,
+      displayName: user.displayName,
+      // Admins benefit from seeing their role assignment in the
+      // SPA — drives conditional UI for super-admin features later.
+      // Other surfaces (`/api/auth/me`) still omit it.
+      roles: user.roles,
+    });
+  }
+
+  @Get('logout')
+  async logout(@Req() req: Request, @Res() res: Response): Promise<void> {
+    const user = req.session.user;
+    const wasAuthenticated = Boolean(user);
+    const logoutUrl = this.authService.buildLogoutUrl(this.entra.adminPostLogoutRedirectUri);
+
+    await this.sessionEstablisher.destroy({ actor: user, req });
+
+    res.clearCookie(adminSessionCookieName(), { path: '/' });
+    res.clearCookie(csrfCookieName(), { path: '/' });
+    this.logger.log(
+      { event: 'auth.signed_out', surface: 'admin', wasAuthenticated },
+      'AdminAuthLogout',
+    );
+    res.redirect(302, logoutUrl);
+  }
+
+  private redirectWithError(res: Response, kind: AuthCodeFlowError['kind']): void {
+    const url = new URL(this.entra.adminPostLogoutRedirectUri);
+    url.searchParams.set('auth_error', authErrorCode({ kind } as AuthCodeFlowError));
+    res.redirect(302, url.toString());
+  }
+}
+
+function readPreAuthCookie(req: Request): PreAuthPayload | null {
+  const raw = (req.signedCookies as Record<string, unknown>)[PRE_AUTH_COOKIE_NAME];
+  if (typeof raw !== 'string') {
+    return null;
+  }
+  try {
+    return JSON.parse(raw) as PreAuthPayload;
+  } catch {
+    return null;
+  }
+}

apps/portal-bff/src/admin/admin.module.ts

@@ -1,21 +1,34 @@
 import { Module } from '@nestjs/common';
+import { AuthModule } from '../auth/auth.module';
+import { AdminAuthController } from './admin-auth.controller';
 import { AdminController } from './admin.controller';
 import { AdminRoleGuard } from './admin-role.guard';
 
 /**
  * `AdminModule` — root of the `/api/admin/*` surface per ADR-0020.
  *
- * v1 ships the self-test endpoint only (`GET /api/admin/me`). The
- * functional admin modules (audit log viewer, CMS, menu management,
- * user list) land as separate sub-modules consumed from here once
- * the distinct admin session + the audit query endpoint are in
- * place — see the chantier sequence in `notes/handoff.md`.
+ * v1 ships:
+ *   - `GET /api/admin/me` (self-test, guarded by `@RequireAdmin`).
+ *   - `/api/admin/auth/{login,callback,me,logout}` — the distinct
+ *     admin auth flow that establishes the `__Host-portal_admin_session`
+ *     per ADR-0020 §"Sessions — distinct from `portal-shell`".
+ *
+ * Imports `AuthModule` to consume `AuthService`, `SessionEstablisher`,
+ * and `ENTRA_CONFIG` — the auth flow itself is shared with the
+ * user-portal `AuthController`; what differs is the redirect URIs
+ * passed in (admin-specific) and the session that gets populated
+ * (resolved by the path-routed session middleware in `main.ts`).
+ *
+ * The functional admin modules (audit log viewer, CMS, menu
+ * management, user list) land as separate sub-modules consumed from
+ * here in upcoming PRs.
  *
  * `AuditWriter` (required by `AdminRoleGuard`) is provided globally
- * by `AuditModule`, so no extra import is needed here.
+ * by `AuditModule`, so no extra import is needed for it.
  */
 @Module({
-  controllers: [AdminController],
+  imports: [AuthModule],
+  controllers: [AdminController, AdminAuthController],
   providers: [AdminRoleGuard],
 })
 export class AdminModule {}

apps/portal-bff/src/auth/auth.controller.spec.ts

@@ -7,6 +7,7 @@ import { PRE_AUTH_COOKIE_NAME, PRE_AUTH_COOKIE_TTL_MS } from './auth.cookie';
 import { AuthCodeFlowException } from './auth.errors';
 import type { AuthService, AuthenticatedUser, PreAuthPayload } from './auth.service';
 import type { EntraConfig } from './entra-config.token';
+import { SessionEstablisher } from './session-establisher.service';
 
 const ENTRA: EntraConfig = {
   instanceUrl: 'https://login.microsoftonline.com/',
@@ -15,6 +16,8 @@ const ENTRA: EntraConfig = {
   clientSecret: 's3cret',
   redirectUri: 'http://localhost:3000/api/auth/callback',
   postLogoutRedirectUri: 'http://localhost:4200/',
+  adminRedirectUri: 'http://localhost:3000/api/admin/auth/callback',
+  adminPostLogoutRedirectUri: 'http://localhost:4201/',
   authority: 'https://login.microsoftonline.com/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
 };
 
@@ -140,13 +143,21 @@ function makeController(opts?: { completeAuthCodeFlow?: jest.Mock }): Controller
     sessionExpired: jest.fn().mockResolvedValue(undefined),
   };
   const logger = makeLoggerStub();
+  // Real SessionEstablisher with the same mocks the legacy tests
+  // already wire — keeps the behavioural assertions on session
+  // fields / audit calls untouched after the controller refactor.
+  const sessionEstablisher = new SessionEstablisher(
+    logger as unknown as Logger,
+    userSessionIndex as unknown as UserSessionIndexService,
+    audit as unknown as AuditWriter,
+  );
   return {
     controller: new AuthController(
       service,
       logger as unknown as Logger,
       ENTRA,
-      userSessionIndex as unknown as UserSessionIndexService,
       audit as unknown as AuditWriter,
+      sessionEstablisher,
     ),
     beginAuthCodeFlow,
     completeAuthCodeFlow,
@@ -214,7 +225,12 @@ describe('AuthController.callback', () => {
     await controller.callback(req, res, 'auth-code', PRE_AUTH.state);
 
     expect(res.clearCookie).toHaveBeenCalledWith(PRE_AUTH_COOKIE_NAME, expect.any(Object));
-    expect(completeAuthCodeFlow).toHaveBeenCalledWith('auth-code', PRE_AUTH.state, PRE_AUTH);
+    expect(completeAuthCodeFlow).toHaveBeenCalledWith(
+      'auth-code',
+      PRE_AUTH.state,
+      PRE_AUTH,
+      ENTRA.redirectUri,
+    );
     // The resolved user must be on the session before the redirect
     // so the subsequent /me call sees a populated payload.
     expect(session.user).toEqual(USER);
@@ -222,6 +238,7 @@ describe('AuthController.callback', () => {
     expect(logger.log).toHaveBeenCalledWith(
       expect.objectContaining({
         event: 'auth.signed_in',
+        surface: 'user',
         oid: USER.oid,
         username: USER.username,
         amr: USER.amr,
@@ -565,7 +582,7 @@ describe('AuthController.logout', () => {
     expect(res.clearCookie).toHaveBeenCalledWith('portal_session', { path: '/' });
     expect(res.clearCookie).toHaveBeenCalledWith('portal_csrf', { path: '/' });
     expect(logger.log).toHaveBeenCalledWith(
-      { event: 'auth.signed_out', wasAuthenticated: true },
+      { event: 'auth.signed_out', surface: 'user', wasAuthenticated: true },
       'AuthLogout',
     );
     // Authority + /oauth2/v2.0/logout?post_logout_redirect_uri=…
@@ -617,7 +634,7 @@ describe('AuthController.logout', () => {
     expect(audit.signOut).not.toHaveBeenCalled();
     expect(session.destroy).toHaveBeenCalledTimes(1);
     expect(logger.log).toHaveBeenCalledWith(
-      { event: 'auth.signed_out', wasAuthenticated: false },
+      { event: 'auth.signed_out', surface: 'user', wasAuthenticated: false },
       'AuthLogout',
     );
     expect(res.redirect).toHaveBeenCalled();

apps/portal-bff/src/auth/auth.controller.ts

@@ -1,11 +1,9 @@
-import { randomBytes } from 'node:crypto';
 import { Controller, Get, Inject, Query, Req, Res, UnauthorizedException } 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, sessionCookieName } from '../session/session-cookie';
-import { UserSessionIndexService } from '../session/user-session-index.service';
+import { csrfCookieName } from '../security/csrf-cookie';
+import { sessionCookieName } from '../session/session-cookie';
 import {
   PRE_AUTH_COOKIE_NAME,
   clearPreAuthCookieOptions,
@@ -14,6 +12,7 @@ import {
 import { AuthCodeFlowException, type AuthCodeFlowError, authErrorCode } from './auth.errors';
 import { AuthService, type AuthenticatedUser, type PreAuthPayload } from './auth.service';
 import { ENTRA_CONFIG, type EntraConfig } from './entra-config.token';
+import { SessionEstablisher } from './session-establisher.service';
 
 /**
  * OIDC routes mounted under `/api/auth/` per ADR-0009.
@@ -31,8 +30,8 @@ export class AuthController {
     private readonly authService: AuthService,
     private readonly logger: Logger,
     @Inject(ENTRA_CONFIG) private readonly entra: EntraConfig,
-    private readonly userSessionIndex: UserSessionIndexService,
     private readonly audit: AuditWriter,
+    private readonly sessionEstablisher: SessionEstablisher,
   ) {}
 
   /**
@@ -47,7 +46,9 @@ export class AuthController {
    */
   @Get('login')
   async login(@Res() res: Response): Promise<void> {
-    const { authUrl, preAuthPayload } = await this.authService.beginAuthCodeFlow();
+    const { authUrl, preAuthPayload } = await this.authService.beginAuthCodeFlow(
+      this.entra.redirectUri,
+    );
     res.cookie(PRE_AUTH_COOKIE_NAME, JSON.stringify(preAuthPayload), preAuthCookieOptions());
     res.redirect(302, authUrl);
   }
@@ -117,60 +118,13 @@ export class AuthController {
     }
 
     try {
-      const user = await this.authService.completeAuthCodeFlow(code, state, preAuth);
-      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;
-      // CSRF token per ADR-0009 §"Double-submit CSRF". Server-side
-      // source of truth lives on the session; the cookie below is
-      // the SPA's read-only mirror used to echo the value in the
-      // X-CSRF-Token header.
-      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. The stamp reflects "the
-      // session was just established with whatever assurance Entra
-      // returned"; `RequireMfaGuard` measures freshness against it.
-      // Refreshed by future step-up re-auth flows.
-      req.session.mfaVerifiedAt = now;
-      // Force the save before the redirect: express-session writes
-      // on response end, but the 302 we're about to emit closes the
-      // response before the async store-write would otherwise
-      // complete. Without this, the browser hits the SPA before
-      // Redis carries the new payload.
-      await saveSession(req);
-      // Mirror the CSRF token to a JS-readable cookie. maxAge
-      // matches the session's idle TTL so the cookie expires at
-      // the same time as the session (rolling, refreshed on each
-      // request alongside express-session's own cookie).
-      res.cookie(csrfCookieName(), csrfToken, csrfCookieOptions(idleSeconds * 1000));
-      // Register the freshly-minted session id in the per-user
-      // index so a future admin "logout everywhere" can enumerate
-      // and revoke. Best-effort: a Redis hiccup here doesn't fail
-      // sign-in (the service swallows + logs).
-      await this.userSessionIndex.add(user.oid, req.sessionID);
-      // First write to the audit trail — blocking, 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
-      // Nest's default exception filter. Same posture as the
-      // session.save() above.
-      await this.audit.signIn({ actor: user, sessionId: req.sessionID });
-      this.logger.log(
-        {
-          event: 'auth.signed_in',
-          oid: user.oid,
-          tid: user.tid,
-          username: user.username,
-          amr: user.amr,
-        },
-        'AuthCallback',
+      const user = await this.authService.completeAuthCodeFlow(
+        code,
+        state,
+        preAuth,
+        this.entra.redirectUri,
       );
+      await this.sessionEstablisher.establish({ user, req, res, surface: 'user' });
       res.redirect(302, this.entra.postLogoutRedirectUri);
     } catch (err) {
       if (err instanceof AuthCodeFlowException) {
@@ -226,41 +180,13 @@ export class AuthController {
   async logout(@Req() req: Request, @Res() res: Response): Promise<void> {
     const user = req.session.user;
     const wasAuthenticated = Boolean(user);
-    const sessionId = req.sessionID;
-    const logoutUrl = this.authService.buildLogoutUrl();
+    const logoutUrl = this.authService.buildLogoutUrl(this.entra.postLogoutRedirectUri);
 
-    // Drop the user_sessions index entry before destroy() removes
-    // the session id from `req`. Skipped on already-anonymous
-    // requests (nothing was ever added).
-    if (user) {
-      await this.userSessionIndex.remove(user.oid, sessionId);
-      // Audit the sign-out before tearing the session down — once
-      // destroy() runs we lose the actor id. Blocking per ADR-0013:
-      // if the audit row can't be written, the user does NOT get a
-      // "you're logged out" experience, because we can't certify
-      // the sign-out happened.
-      await this.audit.signOut({ actor: user, sessionId });
-    }
-
-    try {
-      await destroySession(req);
-    } catch (err) {
-      // The Redis DEL failed — log and continue. Clearing the
-      // cookie still gets the user effectively logged out from the
-      // BFF's point of view; the orphan Redis key will hit its idle
-      // TTL on its own.
-      this.logger.error(
-        {
-          event: 'session.destroy_failed',
-          message: err instanceof Error ? err.message : String(err),
-        },
-        'AuthLogout',
-      );
-    }
+    await this.sessionEstablisher.destroy({ actor: user, req });
 
     res.clearCookie(sessionCookieName(), { path: '/' });
     res.clearCookie(csrfCookieName(), { path: '/' });
-    this.logger.log({ event: 'auth.signed_out', wasAuthenticated }, 'AuthLogout');
+    this.logger.log({ event: 'auth.signed_out', surface: 'user', wasAuthenticated }, 'AuthLogout');
     res.redirect(302, logoutUrl);
   }
 
@@ -287,18 +213,6 @@ function toPublicUser(user: AuthenticatedUser): PublicUser {
   };
 }
 
-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()));
-  });
-}
-
 function readPreAuthCookie(req: Request): PreAuthPayload | null {
   const raw = (req.signedCookies as Record<string, unknown>)[PRE_AUTH_COOKIE_NAME];
   if (typeof raw !== 'string') {

apps/portal-bff/src/auth/auth.module.spec.ts

@@ -42,6 +42,8 @@ const VALID = {
   ENTRA_CLIENT_SECRET: 's3cret-value-from-entra',
   ENTRA_REDIRECT_URI: 'http://localhost:3000/api/auth/callback',
   ENTRA_POST_LOGOUT_REDIRECT_URI: 'http://localhost:4200/',
+  ENTRA_ADMIN_REDIRECT_URI: 'http://localhost:3000/api/admin/auth/callback',
+  ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI: 'http://localhost:4201/',
   // Well-formed but unreachable Redis URL — `ioredis` opens the
   // socket lazily so the module compiles without any network access.
   REDIS_URL: 'redis://default:test-pass@127.0.0.1:65535/0',

apps/portal-bff/src/auth/auth.module.ts

@@ -8,6 +8,7 @@ import { AuthService } from './auth.service';
 import { ENTRA_CONFIG, type EntraConfig } from './entra-config.token';
 import { MSAL_CLIENT } from './msal-client.token';
 import { RequireMfaGuard } from './require-mfa.guard';
+import { SessionEstablisher } from './session-establisher.service';
 
 /**
  * Auth module — owns the Entra ID configuration, the MSAL Node
@@ -45,6 +46,7 @@ import { RequireMfaGuard } from './require-mfa.guard';
   providers: [
     AuthService,
     RequireMfaGuard,
+    SessionEstablisher,
     {
       provide: ENTRA_CONFIG,
       useFactory: () => assertEntraConfig(),
@@ -90,6 +92,6 @@ import { RequireMfaGuard } from './require-mfa.guard';
         }),
     },
   ],
-  exports: [ENTRA_CONFIG, MSAL_CLIENT, RequireMfaGuard],
+  exports: [ENTRA_CONFIG, MSAL_CLIENT, RequireMfaGuard, AuthService, SessionEstablisher],
 })
 export class AuthModule {}

apps/portal-bff/src/auth/auth.service.spec.ts

@@ -11,6 +11,8 @@ const ENTRA: EntraConfig = {
   clientSecret: 's3cret',
   redirectUri: 'http://localhost:3000/api/auth/callback',
   postLogoutRedirectUri: 'http://localhost:4200/',
+  adminRedirectUri: 'http://localhost:3000/api/admin/auth/callback',
+  adminPostLogoutRedirectUri: 'http://localhost:4201/',
   authority: 'https://login.microsoftonline.com/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
 };
 
@@ -71,7 +73,7 @@ const PRE_AUTH_OK: PreAuthPayload = {
 describe('AuthService.beginAuthCodeFlow', () => {
   it('builds the auth URL with the configured redirect, OIDC scopes, S256 challenge', async () => {
     const { service, getAuthCodeUrl } = makeService();
-    await service.beginAuthCodeFlow();
+    await service.beginAuthCodeFlow(ENTRA.redirectUri);
     expect(getAuthCodeUrl).toHaveBeenCalledTimes(1);
     const arg = getAuthCodeUrl.mock.calls[0]?.[0] as Record<string, unknown>;
     expect(arg['redirectUri']).toBe(ENTRA.redirectUri);
@@ -83,7 +85,7 @@ describe('AuthService.beginAuthCodeFlow', () => {
 
   it('returns the pre-auth payload with state + codeVerifier matching what MSAL was called with', async () => {
     const { service, getAuthCodeUrl } = makeService();
-    const { preAuthPayload } = await service.beginAuthCodeFlow();
+    const { preAuthPayload } = await service.beginAuthCodeFlow(ENTRA.redirectUri);
     const arg = getAuthCodeUrl.mock.calls[0]?.[0] as Record<string, unknown>;
     expect(preAuthPayload.state).toBe(arg['state']);
     expect(preAuthPayload.codeVerifier).not.toBe(arg['codeChallenge']);
@@ -92,8 +94,8 @@ describe('AuthService.beginAuthCodeFlow', () => {
 
   it('generates a fresh state + verifier on every call', async () => {
     const { service } = makeService();
-    const a = await service.beginAuthCodeFlow();
-    const b = await service.beginAuthCodeFlow();
+    const a = await service.beginAuthCodeFlow(ENTRA.redirectUri);
+    const b = await service.beginAuthCodeFlow(ENTRA.redirectUri);
     expect(a.preAuthPayload.state).not.toBe(b.preAuthPayload.state);
     expect(a.preAuthPayload.codeVerifier).not.toBe(b.preAuthPayload.codeVerifier);
   });
@@ -106,6 +108,7 @@ describe('AuthService.completeAuthCodeFlow', () => {
       'auth-code',
       PRE_AUTH_OK.state,
       PRE_AUTH_OK,
+      ENTRA.redirectUri,
       PRE_AUTH_OK.createdAt + 1_000,
     );
     expect(acquireTokenByCode).toHaveBeenCalledWith({
@@ -127,7 +130,13 @@ describe('AuthService.completeAuthCodeFlow', () => {
   it('throws state-mismatch when the query state differs from the cookie state', async () => {
     const { service } = makeService();
     await expect(
-      service.completeAuthCodeFlow('code', 'other-state', PRE_AUTH_OK, PRE_AUTH_OK.createdAt),
+      service.completeAuthCodeFlow(
+        'code',
+        'other-state',
+        PRE_AUTH_OK,
+        ENTRA.redirectUri,
+        PRE_AUTH_OK.createdAt,
+      ),
     ).rejects.toMatchObject({ failure: { kind: 'state-mismatch' } });
   });
 
@@ -135,7 +144,7 @@ describe('AuthService.completeAuthCodeFlow', () => {
     const { service } = makeService();
     const now = PRE_AUTH_OK.createdAt + PRE_AUTH_COOKIE_TTL_MS + 1;
     await expect(
-      service.completeAuthCodeFlow('code', PRE_AUTH_OK.state, PRE_AUTH_OK, now),
+      service.completeAuthCodeFlow('code', PRE_AUTH_OK.state, PRE_AUTH_OK, ENTRA.redirectUri, now),
     ).rejects.toMatchObject({ failure: { kind: 'flow-expired' } });
   });
 
@@ -146,6 +155,7 @@ describe('AuthService.completeAuthCodeFlow', () => {
       'code',
       PRE_AUTH_OK.state,
       PRE_AUTH_OK,
+      ENTRA.redirectUri,
       PRE_AUTH_OK.createdAt,
     );
     // `amr` flows through as an empty array; MFA enforcement is
@@ -163,6 +173,7 @@ describe('AuthService.completeAuthCodeFlow', () => {
       'code',
       PRE_AUTH_OK.state,
       PRE_AUTH_OK,
+      ENTRA.redirectUri,
       PRE_AUTH_OK.createdAt,
     );
     expect(user.roles).toEqual(['admin', 'editor']);
@@ -175,6 +186,7 @@ describe('AuthService.completeAuthCodeFlow', () => {
       'code',
       PRE_AUTH_OK.state,
       PRE_AUTH_OK,
+      ENTRA.redirectUri,
       PRE_AUTH_OK.createdAt,
     );
     expect(user.roles).toEqual([]);
@@ -187,6 +199,7 @@ describe('AuthService.completeAuthCodeFlow', () => {
       'code',
       PRE_AUTH_OK.state,
       PRE_AUTH_OK,
+      ENTRA.redirectUri,
       PRE_AUTH_OK.createdAt,
     );
     expect(user.roles).toEqual([]);
@@ -201,6 +214,7 @@ describe('AuthService.completeAuthCodeFlow', () => {
       'code',
       PRE_AUTH_OK.state,
       PRE_AUTH_OK,
+      ENTRA.redirectUri,
       PRE_AUTH_OK.createdAt,
     );
     expect(user.roles).toEqual(['admin', 'editor']);
@@ -210,7 +224,13 @@ describe('AuthService.completeAuthCodeFlow', () => {
     const acquireTokenByCode = jest.fn().mockRejectedValue(new Error('AADSTS70008'));
     const { service } = makeService({ acquireTokenByCode });
     await expect(
-      service.completeAuthCodeFlow('code', PRE_AUTH_OK.state, PRE_AUTH_OK, PRE_AUTH_OK.createdAt),
+      service.completeAuthCodeFlow(
+        'code',
+        PRE_AUTH_OK.state,
+        PRE_AUTH_OK,
+        ENTRA.redirectUri,
+        PRE_AUTH_OK.createdAt,
+      ),
     ).rejects.toMatchObject({
       failure: { kind: 'token-exchange-failed', cause: 'AADSTS70008' },
     });
@@ -220,7 +240,13 @@ describe('AuthService.completeAuthCodeFlow', () => {
     const acquireTokenByCode = jest.fn().mockResolvedValue(null);
     const { service } = makeService({ acquireTokenByCode });
     await expect(
-      service.completeAuthCodeFlow('code', PRE_AUTH_OK.state, PRE_AUTH_OK, PRE_AUTH_OK.createdAt),
+      service.completeAuthCodeFlow(
+        'code',
+        PRE_AUTH_OK.state,
+        PRE_AUTH_OK,
+        ENTRA.redirectUri,
+        PRE_AUTH_OK.createdAt,
+      ),
     ).rejects.toBeInstanceOf(AuthCodeFlowException);
   });
 
@@ -231,7 +257,13 @@ describe('AuthService.completeAuthCodeFlow', () => {
     } as unknown as AuthenticationResult);
     const { service } = makeService({ acquireTokenByCode });
     await expect(
-      service.completeAuthCodeFlow('code', PRE_AUTH_OK.state, PRE_AUTH_OK, PRE_AUTH_OK.createdAt),
+      service.completeAuthCodeFlow(
+        'code',
+        PRE_AUTH_OK.state,
+        PRE_AUTH_OK,
+        ENTRA.redirectUri,
+        PRE_AUTH_OK.createdAt,
+      ),
     ).rejects.toMatchObject({
       failure: { kind: 'token-exchange-failed', cause: /oid/ },
     });
@@ -241,19 +273,19 @@ describe('AuthService.completeAuthCodeFlow', () => {
 describe('AuthService.buildLogoutUrl', () => {
   it('targets the v2.0 logout endpoint on the configured authority', () => {
     const { service } = makeService();
-    const url = new URL(service.buildLogoutUrl());
+    const url = new URL(service.buildLogoutUrl(ENTRA.postLogoutRedirectUri));
     expect(url.origin + url.pathname).toBe(`${ENTRA.authority}/oauth2/v2.0/logout`);
   });
 
   it('includes the post_logout_redirect_uri query param', () => {
     const { service } = makeService();
-    const url = new URL(service.buildLogoutUrl());
+    const url = new URL(service.buildLogoutUrl(ENTRA.postLogoutRedirectUri));
     expect(url.searchParams.get('post_logout_redirect_uri')).toBe(ENTRA.postLogoutRedirectUri);
   });
 
   it('does not pass id_token_hint (v1 does not persist the id_token yet)', () => {
     const { service } = makeService();
-    const url = new URL(service.buildLogoutUrl());
+    const url = new URL(service.buildLogoutUrl(ENTRA.postLogoutRedirectUri));
     expect(url.searchParams.has('id_token_hint')).toBe(false);
   });
 });

apps/portal-bff/src/auth/auth.service.ts

@@ -81,13 +81,18 @@ export class AuthService {
    * MSAL Node owns the PKCE code generation (`CryptoProvider`) so
    * the verifier / challenge pair is canonical. The state nonce is
    * a fresh GUID per flow.
+   *
+   * `redirectUri` is passed by the caller (user-portal or
+   * admin-portal controller) per ADR-0020 §"Sessions — distinct
+   * from `portal-shell`". Same MSAL client, distinct redirect URI →
+   * Entra routes the callback to the matching session.
    */
-  async beginAuthCodeFlow(): Promise<AuthCodeFlowStart> {
+  async beginAuthCodeFlow(redirectUri: string): Promise<AuthCodeFlowStart> {
     const { verifier, challenge } = await this.crypto.generatePkceCodes();
     const state = this.crypto.createNewGuid();
 
     const authUrl = await this.msal.getAuthCodeUrl({
-      redirectUri: this.config.redirectUri,
+      redirectUri,
       scopes: [...SCOPES],
       state,
       codeChallenge: challenge,
@@ -121,6 +126,7 @@ export class AuthService {
     code: string,
     state: string,
     preAuth: PreAuthPayload,
+    redirectUri: string,
     now: number = Date.now(),
   ): Promise<AuthenticatedUser> {
     if (state !== preAuth.state) {
@@ -135,7 +141,7 @@ export class AuthService {
       result = await this.msal.acquireTokenByCode({
         code,
         codeVerifier: preAuth.codeVerifier,
-        redirectUri: this.config.redirectUri,
+        redirectUri,
         scopes: [...SCOPES],
       });
     } catch (err) {
@@ -167,9 +173,9 @@ export class AuthService {
    * lands with downstream API support per ADR-0014. The account
    * picker is the safer default in the interim.
    */
-  buildLogoutUrl(): string {
+  buildLogoutUrl(postLogoutRedirectUri: string): string {
     const url = new URL(`${this.config.authority}/oauth2/v2.0/logout`);
-    url.searchParams.set('post_logout_redirect_uri', this.config.postLogoutRedirectUri);
+    url.searchParams.set('post_logout_redirect_uri', postLogoutRedirectUri);
     return url.toString();
   }
 

apps/portal-bff/src/auth/session-establisher.service.spec.ts

@@ -0,0 +1,198 @@
+import type { Request, Response } from 'express';
+import type { Logger } from 'nestjs-pino';
+import type { AuditWriter } from '../audit/audit.service';
+import type { UserSessionIndexService } from '../session/user-session-index.service';
+import type { AuthenticatedUser } from './auth.service';
+import { SessionEstablisher } from './session-establisher.service';
+
+const USER: AuthenticatedUser = {
+  oid: 'user-oid',
+  tid: 'tenant-1',
+  username: 'jane@apf.example',
+  displayName: 'Jane Doe',
+  amr: ['pwd', 'mfa'],
+  roles: [],
+};
+
+function makeReqStub(opts?: { sessionID?: string; sessionUser?: AuthenticatedUser }): Request {
+  const session: Record<string, unknown> = {
+    save: jest.fn((cb: (err?: Error) => void) => cb()),
+    destroy: jest.fn((cb: (err?: Error) => void) => cb()),
+  };
+  if (opts?.sessionUser !== undefined) {
+    session['user'] = opts.sessionUser;
+  }
+  return {
+    session,
+    sessionID: opts?.sessionID ?? 'sid-test',
+  } as unknown as Request;
+}
+
+function makeResStub(): Response & { cookie: jest.Mock; clearCookie: jest.Mock } {
+  const res = {
+    cookie: jest.fn(),
+    clearCookie: jest.fn(),
+  };
+  res.cookie.mockReturnValue(res);
+  res.clearCookie.mockReturnValue(res);
+  return res as unknown as Response & typeof res;
+}
+
+function makeLoggerStub() {
+  return {
+    log: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+  };
+}
+
+interface Fixture {
+  est: SessionEstablisher;
+  index: { add: jest.Mock; remove: jest.Mock; list: jest.Mock };
+  audit: { signIn: jest.Mock; signOut: jest.Mock };
+  logger: ReturnType<typeof makeLoggerStub>;
+}
+
+function makeFixture(): Fixture {
+  const index = {
+    add: jest.fn().mockResolvedValue(undefined),
+    remove: jest.fn().mockResolvedValue(undefined),
+    list: jest.fn().mockResolvedValue([]),
+  };
+  const audit = {
+    signIn: jest.fn().mockResolvedValue(undefined),
+    signOut: jest.fn().mockResolvedValue(undefined),
+  };
+  const logger = makeLoggerStub();
+  const est = new SessionEstablisher(
+    logger as unknown as Logger,
+    index as unknown as UserSessionIndexService,
+    audit as unknown as AuditWriter,
+  );
+  return { est, index, audit, logger };
+}
+
+describe('SessionEstablisher.establish', () => {
+  it('writes user + createdAt + absoluteExpiresAt + csrfToken + mfaVerifiedAt on the session', async () => {
+    const { est } = makeFixture();
+    const req = makeReqStub();
+    const res = makeResStub();
+    const before = Date.now();
+    await est.establish({ user: USER, req, res, surface: 'user' });
+    const after = Date.now();
+    const sess = (req as unknown as { session: Record<string, unknown> }).session;
+    expect(sess['user']).toEqual(USER);
+    expect(sess['createdAt']).toBeGreaterThanOrEqual(before);
+    expect(sess['createdAt']).toBeLessThanOrEqual(after);
+    // createdAt + mfaVerifiedAt share a clock reading.
+    expect(sess['mfaVerifiedAt']).toBe(sess['createdAt']);
+    expect(sess['absoluteExpiresAt']).toBeGreaterThan(sess['createdAt'] as number);
+    expect(typeof sess['csrfToken']).toBe('string');
+    expect((sess['csrfToken'] as string).length).toBeGreaterThan(20);
+  });
+
+  it('saves the session before returning (no race with the controller redirect)', async () => {
+    const { est } = makeFixture();
+    const req = makeReqStub();
+    const res = makeResStub();
+    await est.establish({ user: USER, req, res, surface: 'user' });
+    const sess = (req as unknown as { session: { save: jest.Mock } }).session;
+    expect(sess.save).toHaveBeenCalledTimes(1);
+  });
+
+  it('mirrors the CSRF token to a JS-readable cookie', async () => {
+    const { est } = makeFixture();
+    const req = makeReqStub();
+    const res = makeResStub();
+    await est.establish({ user: USER, req, res, surface: 'user' });
+    const sess = (req as unknown as { session: Record<string, unknown> }).session;
+    expect(res.cookie).toHaveBeenCalledWith(
+      expect.stringMatching(/csrf/),
+      sess['csrfToken'],
+      expect.objectContaining({ httpOnly: false }),
+    );
+  });
+
+  it('adds the session id to the user_sessions index', async () => {
+    const { est, index } = makeFixture();
+    const req = makeReqStub({ sessionID: 'sid-7' });
+    const res = makeResStub();
+    await est.establish({ user: USER, req, res, surface: 'user' });
+    expect(index.add).toHaveBeenCalledWith(USER.oid, 'sid-7');
+  });
+
+  it('emits the auth.sign_in audit row', async () => {
+    const { est, audit } = makeFixture();
+    const req = makeReqStub({ sessionID: 'sid-7' });
+    const res = makeResStub();
+    await est.establish({ user: USER, req, res, surface: 'user' });
+    expect(audit.signIn).toHaveBeenCalledWith({ actor: USER, sessionId: 'sid-7' });
+  });
+
+  it('logs the success event with the surface tag', async () => {
+    const { est, logger } = makeFixture();
+    const req = makeReqStub();
+    const res = makeResStub();
+    await est.establish({ user: USER, req, res, surface: 'admin' });
+    expect(logger.log).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: 'auth.signed_in',
+        surface: 'admin',
+        oid: USER.oid,
+      }),
+      'AuthCallback',
+    );
+  });
+
+  it('propagates audit failures (blocking per ADR-0013)', async () => {
+    const { est, audit } = makeFixture();
+    audit.signIn.mockRejectedValueOnce(new Error('audit_writer denied'));
+    const req = makeReqStub();
+    const res = makeResStub();
+    await expect(est.establish({ user: USER, req, res, surface: 'user' })).rejects.toThrow(
+      'audit_writer denied',
+    );
+  });
+});
+
+describe('SessionEstablisher.destroy', () => {
+  it('removes from index + audits signOut + destroys session when actor is set', async () => {
+    const { est, index, audit } = makeFixture();
+    const req = makeReqStub({ sessionID: 'sid-9', sessionUser: USER });
+    await est.destroy({ actor: USER, req });
+    expect(index.remove).toHaveBeenCalledWith(USER.oid, 'sid-9');
+    expect(audit.signOut).toHaveBeenCalledWith({ actor: USER, sessionId: 'sid-9' });
+    const sess = (req as unknown as { session: { destroy: jest.Mock } }).session;
+    expect(sess.destroy).toHaveBeenCalledTimes(1);
+  });
+
+  it('still destroys the session for anonymous sign-outs but skips index + audit', async () => {
+    const { est, index, audit } = makeFixture();
+    const req = makeReqStub();
+    await est.destroy({ actor: undefined, req });
+    expect(index.remove).not.toHaveBeenCalled();
+    expect(audit.signOut).not.toHaveBeenCalled();
+    const sess = (req as unknown as { session: { destroy: jest.Mock } }).session;
+    expect(sess.destroy).toHaveBeenCalledTimes(1);
+  });
+
+  it('logs but does not propagate when req.session.destroy fails (Redis hiccup)', async () => {
+    const { est, logger } = makeFixture();
+    const req = makeReqStub();
+    (req as unknown as { session: { destroy: jest.Mock } }).session.destroy = jest.fn(
+      (cb: (err?: Error) => void) => cb(new Error('redis down')),
+    );
+    await expect(est.destroy({ actor: USER, req })).resolves.toBeUndefined();
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.objectContaining({ event: 'session.destroy_failed' }),
+      'AuthLogout',
+    );
+  });
+
+  it('propagates audit failures from signOut (blocking per ADR-0013)', async () => {
+    const { est, audit } = makeFixture();
+    audit.signOut.mockRejectedValueOnce(new Error('audit_writer denied'));
+    const req = makeReqStub({ sessionUser: USER });
+    await expect(est.destroy({ actor: USER, req })).rejects.toThrow('audit_writer denied');
+  });
+});

apps/portal-bff/src/auth/session-establisher.service.ts

@@ -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()));
+  });
+}

apps/portal-bff/src/config/check-entra-config.spec.ts

@@ -7,6 +7,8 @@ const VALID = {
   ENTRA_CLIENT_SECRET: 's3cret-value-from-entra',
   ENTRA_REDIRECT_URI: 'http://localhost:3000/api/auth/callback',
   ENTRA_POST_LOGOUT_REDIRECT_URI: 'http://localhost:4200/',
+  ENTRA_ADMIN_REDIRECT_URI: 'http://localhost:3000/api/admin/auth/callback',
+  ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI: 'http://localhost:4201/',
 };
 
 describe('assertEntraConfig', () => {
@@ -38,9 +40,21 @@ describe('assertEntraConfig', () => {
     expect(config.clientSecret).toBe(VALID.ENTRA_CLIENT_SECRET);
     expect(config.redirectUri).toBe(VALID.ENTRA_REDIRECT_URI);
     expect(config.postLogoutRedirectUri).toBe(VALID.ENTRA_POST_LOGOUT_REDIRECT_URI);
+    expect(config.adminRedirectUri).toBe(VALID.ENTRA_ADMIN_REDIRECT_URI);
+    expect(config.adminPostLogoutRedirectUri).toBe(VALID.ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI);
     expect(config.authority).toBe(`${VALID.ENTRA_INSTANCE_URL}${VALID.ENTRA_TENANT_ID}`);
   });
 
+  it('throws when ENTRA_ADMIN_REDIRECT_URI equals ENTRA_REDIRECT_URI (would collapse the two surfaces)', () => {
+    process.env['ENTRA_ADMIN_REDIRECT_URI'] = VALID.ENTRA_REDIRECT_URI;
+    expect(() => assertEntraConfig()).toThrow(/must differ from ENTRA_REDIRECT_URI/);
+  });
+
+  it('rejects ENTRA_ADMIN_REDIRECT_URI when not a valid URL', () => {
+    process.env['ENTRA_ADMIN_REDIRECT_URI'] = 'nope';
+    expect(() => assertEntraConfig()).toThrow(/ENTRA_ADMIN_REDIRECT_URI is not a valid URL/);
+  });
+
   it('throws listing every missing required key', () => {
     delete process.env['ENTRA_CLIENT_ID'];
     delete process.env['ENTRA_CLIENT_SECRET'];

apps/portal-bff/src/config/check-entra-config.ts

@@ -28,10 +28,25 @@ export interface EntraConfig {
   readonly clientId: string;
   /** Confidential client secret. */
   readonly clientSecret: string;
-  /** Where Entra sends the user after authentication — `/auth/callback`. */
+  /** Where Entra sends the user after authentication — `/api/auth/callback`. */
   readonly redirectUri: string;
   /** Where Entra sends the user after RP-initiated logout. */
   readonly postLogoutRedirectUri: string;
+  /**
+   * Admin-surface callback URL — `/api/admin/auth/callback`. Distinct
+   * from {@link redirectUri} per ADR-0020 §"Sessions — distinct from
+   * `portal-shell`" so Entra knows which callback handler (and
+   * therefore which session) the auth flow is establishing.
+   * Both URIs must be registered on the same Entra app registration.
+   */
+  readonly adminRedirectUri: string;
+  /**
+   * Where Entra sends the admin user after RP-initiated logout from
+   * the admin surface. Typically the admin SPA's landing page — kept
+   * distinct from {@link postLogoutRedirectUri} so an operator can
+   * route admin sign-outs to a different page than user sign-outs.
+   */
+  readonly adminPostLogoutRedirectUri: string;
   /**
    * Convenience: the full authority URL passed to MSAL Node
    * (`${instanceUrl}${tenantId}`). Computed once so the rest of the
@@ -47,6 +62,8 @@ const REQUIRED_KEYS = [
   'ENTRA_CLIENT_SECRET',
   'ENTRA_REDIRECT_URI',
   'ENTRA_POST_LOGOUT_REDIRECT_URI',
+  'ENTRA_ADMIN_REDIRECT_URI',
+  'ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI',
 ] as const;
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -70,6 +87,8 @@ export function assertEntraConfig(): EntraConfig {
   const clientSecret = process.env['ENTRA_CLIENT_SECRET'] as string;
   const redirectUri = process.env['ENTRA_REDIRECT_URI'] as string;
   const postLogoutRedirectUri = process.env['ENTRA_POST_LOGOUT_REDIRECT_URI'] as string;
+  const adminRedirectUri = process.env['ENTRA_ADMIN_REDIRECT_URI'] as string;
+  const adminPostLogoutRedirectUri = process.env['ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI'] as string;
 
   assertUrl('ENTRA_INSTANCE_URL', instanceUrl, ['https:']);
   if (!instanceUrl.endsWith('/')) {
@@ -87,6 +106,24 @@ export function assertEntraConfig(): EntraConfig {
 
   assertUrl('ENTRA_REDIRECT_URI', redirectUri, ['http:', 'https:']);
   assertUrl('ENTRA_POST_LOGOUT_REDIRECT_URI', postLogoutRedirectUri, ['http:', 'https:']);
+  assertUrl('ENTRA_ADMIN_REDIRECT_URI', adminRedirectUri, ['http:', 'https:']);
+  assertUrl('ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI', adminPostLogoutRedirectUri, [
+    'http:',
+    'https:',
+  ]);
+
+  // Admin and user redirect URIs must differ — they're the only
+  // way Entra (and therefore the BFF) tells the two flows apart.
+  // A misconfiguration that points both to the same handler would
+  // silently collapse the two surfaces into one session.
+  if (adminRedirectUri === redirectUri) {
+    throw new Error(
+      `ENTRA_ADMIN_REDIRECT_URI must differ from ENTRA_REDIRECT_URI ` +
+        `so Entra can route the callback to the matching session ` +
+        `(see ADR-0020 §"Sessions — distinct from portal-shell"). ` +
+        `Both are: ${redirectUri}`,
+    );
+  }
 
   return {
     instanceUrl,
@@ -95,6 +132,8 @@ export function assertEntraConfig(): EntraConfig {
     clientSecret,
     redirectUri,
     postLogoutRedirectUri,
+    adminRedirectUri,
+    adminPostLogoutRedirectUri,
     authority: `${instanceUrl}${tenantId}`,
   };
 }

apps/portal-bff/src/main.ts

@@ -19,7 +19,9 @@ import { assertSessionSecret } from './config/check-session-secret';
 import { createRateLimitMiddleware, readRateLimitConfig } from './security/rate-limit.middleware';
 import { CSRF_MIDDLEWARE } from './security/security.token';
 import { StructuredErrorFilter } from './security/structured-error.filter';
+import type { NextFunction, Request, Response } from 'express';
 import {
+  ADMIN_SESSION_MIDDLEWARE,
   SESSION_ABSOLUTE_TIMEOUT_MIDDLEWARE,
   SESSION_MIDDLEWARE,
   type RequestHandler,
@@ -125,12 +127,27 @@ async function bootstrap() {
   // `req.cookies`.
   app.use(cookieParser(sessionSecret));
 
-  // Session middleware (per ADR-0010). Resolved from the Nest
-  // container so it sits on the same `ioredis` client the rest of
-  // the BFF uses, with AES-256-GCM applied to the payload before it
-  // lands in Redis. Mounted after `cookieParser` so the session id
-  // cookie is parsed by the time `express-session` reads it.
-  app.use(app.get<RequestHandler>(SESSION_MIDDLEWARE));
+  // Session middlewares (per ADR-0010 + ADR-0020 §"Sessions — distinct
+  // from `portal-shell`"). Two parallel express-session instances:
+  //
+  //   - `SESSION_MIDDLEWARE` carries `portal_session` / Redis prefix
+  //     `session:` and binds to every path EXCEPT `/api/admin/*`.
+  //   - `ADMIN_SESSION_MIDDLEWARE` carries `portal_admin_session` /
+  //     Redis prefix `session:admin:` and binds to `/api/admin/*` only.
+  //
+  // The dispatch is a tiny wrapper that picks one or the other per
+  // request — running both would have the second overwrite `req.session`
+  // from the first, collapsing the two surfaces. Mounted after
+  // `cookieParser` so the session-id cookie is parsed by the time the
+  // selected middleware reads it.
+  const userSession = app.get<RequestHandler>(SESSION_MIDDLEWARE);
+  const adminSession = app.get<RequestHandler>(ADMIN_SESSION_MIDDLEWARE);
+  app.use((req: Request, res: Response, next: NextFunction) => {
+    if (req.path.startsWith('/api/admin')) {
+      return adminSession(req, res, next);
+    }
+    return userSession(req, res, next);
+  });
 
   // Absolute-timeout enforcement (ADR-0010 §"TTL policy"). Runs on
   // every request that survives `express-session`; if the session

apps/portal-bff/src/session/admin-session-cookie.spec.ts

@@ -0,0 +1,28 @@
+import { adminSessionCookieName } from './admin-session-cookie';
+
+describe('adminSessionCookieName', () => {
+  const originalNodeEnv = process.env['NODE_ENV'];
+
+  afterEach(() => {
+    if (originalNodeEnv === undefined) {
+      delete process.env['NODE_ENV'];
+    } else {
+      process.env['NODE_ENV'] = originalNodeEnv;
+    }
+  });
+
+  it('uses the `__Host-` prefixed name in production', () => {
+    process.env['NODE_ENV'] = 'production';
+    expect(adminSessionCookieName()).toBe('__Host-portal_admin_session');
+  });
+
+  it('uses the unprefixed name in development', () => {
+    process.env['NODE_ENV'] = 'development';
+    expect(adminSessionCookieName()).toBe('portal_admin_session');
+  });
+
+  it('defaults to development naming when NODE_ENV is unset', () => {
+    delete process.env['NODE_ENV'];
+    expect(adminSessionCookieName()).toBe('portal_admin_session');
+  });
+});

apps/portal-bff/src/session/admin-session-cookie.ts

@@ -0,0 +1,21 @@
+/**
+ * Admin-session cookie name per ADR-0020 §"Sessions — distinct from
+ * `portal-shell`". The admin SPA carries `__Host-portal_admin_session`
+ * (prod) so a browser holding both cookies can switch between
+ * portal-shell and portal-admin without one signing the user in to
+ * the other.
+ *
+ * Same `__Host-` posture as the user-portal session: `Secure` + no
+ * `Domain` + `Path=/`. The dev variant drops the prefix because
+ * local servers are plain HTTP.
+ *
+ * The cookie scoping is the only thing keeping the two sessions
+ * apart at the browser level — the BFF further isolates them in
+ * Redis under a distinct key prefix (`session:admin:`).
+ */
+const PRODUCTION_NAME = '__Host-portal_admin_session';
+const DEVELOPMENT_NAME = 'portal_admin_session';
+
+export function adminSessionCookieName(): string {
+  return process.env['NODE_ENV'] === 'production' ? PRODUCTION_NAME : DEVELOPMENT_NAME;
+}

apps/portal-bff/src/session/session.module.ts

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 import { Module } from '@nestjs/common';
 import { RedisStore } from 'connect-redis';
 import expressSession from 'express-session';
+import type { CookieOptions } from 'express';
 import { Logger } from 'nestjs-pino';
 import { assertSessionEncryptionKey } from '../config/check-session-encryption-key';
 import { assertSessionSecret } from '../config/check-session-secret';
@@ -9,10 +10,12 @@ import { RedisModule } from '../redis/redis.module';
 import { REDIS_CLIENT, type Redis } from '../redis/redis.token';
 import { AuditWriter } from '../audit/audit.service';
 import { createAbsoluteTimeoutMiddleware } from './absolute-timeout.middleware';
+import { adminSessionCookieName } from './admin-session-cookie';
 import { adaptIoredisForConnectRedis } from './ioredis-connect-redis-adapter';
 import { SessionDecryptError, decrypt, encrypt } from './session-crypto';
 import { readSessionTimeouts, sessionCookieName, sessionCookieOptions } from './session-cookie';
 import {
+  ADMIN_SESSION_MIDDLEWARE,
   SESSION_ABSOLUTE_TIMEOUT_MIDDLEWARE,
   SESSION_MIDDLEWARE,
   type RequestHandler,
@@ -22,35 +25,108 @@ import {
 import './session.types';
 import { UserSessionIndexService } from './user-session-index.service';
 
+/**
+ * Build a configured `express-session` middleware. Shared between
+ * the user-portal middleware ({@link SESSION_MIDDLEWARE}) and the
+ * admin-portal middleware ({@link ADMIN_SESSION_MIDDLEWARE}) per
+ * ADR-0020 §"Sessions — distinct from `portal-shell`".
+ *
+ * The two surfaces differ only on the cookie name and Redis key
+ * prefix; the TTL policy, encryption key, signing secret, session-id
+ * entropy, and error-handling all come from the same source so a
+ * future hardening (e.g. tighter idle TTL on admin) is a parameter
+ * change rather than a divergent code path.
+ */
+function buildSessionMiddleware(
+  redis: Redis,
+  logger: Logger,
+  opts: { cookieName: string; redisKeyPrefix: string; surfaceTag: 'user' | 'admin' },
+): RequestHandler {
+  const secret = assertSessionSecret();
+  const key = assertSessionEncryptionKey();
+  const timeouts = readSessionTimeouts();
+
+  const store = new RedisStore({
+    // `connect-redis` v9 was rewritten against the `node-redis` v4
+    // command surface; the adapter shims `ioredis` to look the same
+    // for the handful of commands the store actually calls.
+    client: adaptIoredisForConnectRedis(redis) as unknown as never,
+    prefix: opts.redisKeyPrefix,
+    ttl: timeouts.idleSeconds,
+    serializer: {
+      stringify: (sess) => encrypt(JSON.stringify(sess), key),
+      parse: (payload) => {
+        try {
+          return JSON.parse(decrypt(payload, key));
+        } catch (err) {
+          // Tamper, wrong key, or unknown version. The phase-2
+          // audit pipeline (ADR-0013) will turn this into a
+          // first-class audit event; for now we surface a
+          // structured Pino log so ops can spot it. The
+          // `surface` tag lets dashboards split user-portal
+          // decrypt failures from admin-portal ones.
+          logger.warn(
+            {
+              event: 'session.decrypt_failed',
+              surface: opts.surfaceTag,
+              reason: err instanceof SessionDecryptError ? err.message : String(err),
+            },
+            'session',
+          );
+          throw err;
+        }
+      },
+    },
+  });
+
+  const cookie: CookieOptions = sessionCookieOptions(timeouts.idleSeconds);
+
+  return expressSession({
+    name: opts.cookieName,
+    secret,
+    // `crypto.randomBytes(32).toString('base64url')` ⇒ 256
+    // bits of entropy in the session id, per ADR-0010
+    // §"Confirmation".
+    genid: () => randomBytes(32).toString('base64url'),
+    store,
+    // `resave: false` — RedisStore.touch refreshes the TTL on
+    // every request; no need to rewrite the payload.
+    resave: false,
+    // `saveUninitialized: false` — don't create empty session
+    // keys for unauthenticated visitors browsing public
+    // routes. The session is born when the OIDC callback
+    // populates it.
+    saveUninitialized: false,
+    // `rolling: true` — the cookie's `expires` slides forward
+    // on every response, matching the sliding-idle policy.
+    rolling: true,
+    cookie,
+  });
+}
+
 /**
  * Session module — wires `express-session` with a `connect-redis`
  * store on top of the shared `ioredis` client, with AES-256-GCM
  * encryption applied to the JSON payload before it lands in Redis.
  *
- * The configured middleware is exposed as a NestJS provider under
- * the {@link SESSION_MIDDLEWARE} token. `main.ts` resolves it from
- * the application context and mounts it once via `app.use(...)`
- * after `cookie-parser`. Mounting the express-session middleware
- * through DI (rather than constructing it in `main.ts`) keeps it on
- * the same Redis client the rest of the BFF uses, instead of
- * spinning up a second connection at the bootstrap layer.
+ * Two middlewares are provided, path-routed in `main.ts`:
  *
- * What's wired today:
- *   - Express-session middleware on every request (`SESSION_MIDDLEWARE`).
- *   - Absolute-timeout middleware (`SESSION_ABSOLUTE_TIMEOUT_MIDDLEWARE`)
- *     that enforces the 12 h hard ceiling per ADR-0010.
- *   - `UserSessionIndexService`: maintains the
- *     `user_sessions:{userId}` Redis set so a future admin endpoint
- *     can "log out user X everywhere" — write-side hooks live in
- *     the auth controller (create on `/auth/callback`, drop on
- *     `/auth/logout` or absolute-timeout).
+ *   - {@link SESSION_MIDDLEWARE} — user-portal. Cookie
+ *     `portal_session` / `__Host-portal_session`. Redis prefix
+ *     `session:`. Bound to every path except `/api/admin/*`.
  *
- * Out of scope, landing in follow-ups:
- *   - The admin "logout everywhere" route that consumes the
- *     `UserSessionIndexService` (waits on the admin module + the
- *     `@RequireAdmin` / `@RequireMfa` guards).
- *   - Audit-pipeline wiring for `session.decrypt_failed` and
- *     `session.absolute_timeout` (ADR-0013).
+ *   - {@link ADMIN_SESSION_MIDDLEWARE} — admin-portal per ADR-0020.
+ *     Cookie `portal_admin_session` / `__Host-portal_admin_session`.
+ *     Redis prefix `session:admin:`. Bound to `/api/admin/*` only.
+ *
+ * The {@link SESSION_ABSOLUTE_TIMEOUT_MIDDLEWARE} (ADR-0010 §"TTL
+ * policy") and {@link UserSessionIndexService} are shared across
+ * both surfaces — the absolute-timeout check reads `req.session`
+ * which the dispatch has already resolved to one surface or the
+ * other; the user-session index is keyed by Entra `oid`, so an
+ * admin sign-in and a user-portal sign-in by the same person
+ * naturally land in different Redis sets only because the session
+ * id namespaces differ.
  */
 @Module({
   imports: [RedisModule],
@@ -68,66 +144,29 @@ import { UserSessionIndexService } from './user-session-index.service';
     {
       provide: SESSION_MIDDLEWARE,
       inject: [REDIS_CLIENT, Logger],
-      useFactory: (redis: Redis, logger: Logger): RequestHandler => {
-        const secret = assertSessionSecret();
-        const key = assertSessionEncryptionKey();
-        const timeouts = readSessionTimeouts();
-
-        const store = new RedisStore({
-          // `connect-redis` v9 was rewritten against the
-          // `node-redis` v4 command surface; the adapter shims
-          // `ioredis` to look the same for the handful of commands
-          // the store actually calls.
-          client: adaptIoredisForConnectRedis(redis) as unknown as never,
-          prefix: 'session:',
-          ttl: timeouts.idleSeconds,
-          serializer: {
-            stringify: (sess) => encrypt(JSON.stringify(sess), key),
-            parse: (payload) => {
-              try {
-                return JSON.parse(decrypt(payload, key));
-              } catch (err) {
-                // Tamper, wrong key, or unknown version. The phase-2
-                // audit pipeline (ADR-0013) will turn this into a
-                // first-class audit event; for now we surface a
-                // structured Pino log so ops can spot it.
-                logger.warn(
+      useFactory: (redis: Redis, logger: Logger): RequestHandler =>
+        buildSessionMiddleware(redis, logger, {
+          cookieName: sessionCookieName(),
+          redisKeyPrefix: 'session:',
+          surfaceTag: 'user',
+        }),
+    },
     {
-                    event: 'session.decrypt_failed',
-                    reason: err instanceof SessionDecryptError ? err.message : String(err),
-                  },
-                  'session',
-                );
-                throw err;
-              }
-            },
-          },
-        });
-
-        return expressSession({
-          name: sessionCookieName(),
-          secret,
-          // `crypto.randomBytes(32).toString('base64url')` ⇒ 256
-          // bits of entropy in the session id, per ADR-0010
-          // §"Confirmation".
-          genid: () => randomBytes(32).toString('base64url'),
-          store,
-          // `resave: false` — RedisStore.touch refreshes the TTL on
-          // every request; no need to rewrite the payload.
-          resave: false,
-          // `saveUninitialized: false` — don't create empty session
-          // keys for unauthenticated visitors browsing public
-          // routes. The session is born when `/auth/callback`
-          // populates it.
-          saveUninitialized: false,
-          // `rolling: true` — the cookie's `expires` slides forward
-          // on every response, matching the sliding-idle policy.
-          rolling: true,
-          cookie: sessionCookieOptions(timeouts.idleSeconds),
-        });
-      },
+      provide: ADMIN_SESSION_MIDDLEWARE,
+      inject: [REDIS_CLIENT, Logger],
+      useFactory: (redis: Redis, logger: Logger): RequestHandler =>
+        buildSessionMiddleware(redis, logger, {
+          cookieName: adminSessionCookieName(),
+          redisKeyPrefix: 'session:admin:',
+          surfaceTag: 'admin',
+        }),
     },
   ],
-  exports: [SESSION_MIDDLEWARE, SESSION_ABSOLUTE_TIMEOUT_MIDDLEWARE, UserSessionIndexService],
+  exports: [
+    SESSION_MIDDLEWARE,
+    ADMIN_SESSION_MIDDLEWARE,
+    SESSION_ABSOLUTE_TIMEOUT_MIDDLEWARE,
+    UserSessionIndexService,
+  ],
 })
 export class SessionModule {}

apps/portal-bff/src/session/session.token.ts

@@ -1,17 +1,38 @@
 import type { RequestHandler } from 'express';
 
 /**
- * DI token for the configured `express-session` middleware. Resolved
+ * DI token for the user-portal `express-session` middleware. Resolved
  * once at bootstrap (`main.ts`) and mounted with `app.use(...)`
  * after `cookie-parser` so cookies are already parsed when the
  * session middleware reads the session id.
  *
+ * Carries the `portal_session` / `__Host-portal_session` cookie and
+ * persists payloads under the `session:` Redis prefix. Bound to
+ * every path EXCEPT `/api/admin/*` by the dispatch in `main.ts`.
+ *
  * Usage:
  *   const session = app.get<RequestHandler>(SESSION_MIDDLEWARE);
  *   app.use(session);
  */
 export const SESSION_MIDDLEWARE = 'SESSION_MIDDLEWARE';
 
+/**
+ * DI token for the admin-portal `express-session` middleware. Same
+ * underlying `express-session` + `connect-redis` plumbing as
+ * {@link SESSION_MIDDLEWARE}, but configured for the admin surface
+ * per ADR-0020 §"Sessions — distinct from `portal-shell`":
+ *
+ *   - Cookie name: `portal_admin_session` / `__Host-portal_admin_session`.
+ *   - Redis key prefix: `session:admin:`.
+ *   - Same idle / absolute TTL policy (ADR-0010); admin tightening
+ *     can come later through env without code changes.
+ *
+ * Bound to `/api/admin/*` only by the dispatch in `main.ts`. Signing
+ * into one surface does NOT sign the user into the other — Entra
+ * SSO at the IdP level still preserves a click-through experience.
+ */
+export const ADMIN_SESSION_MIDDLEWARE = 'ADMIN_SESSION_MIDDLEWARE';
+
 /**
  * DI token for the absolute-timeout middleware (per ADR-0010 §"TTL
  * policy"). Resolved at bootstrap and mounted in `main.ts`