Production deploy

api.planx.uk/modules/auth/controller.ts

@@ -39,6 +39,7 @@ function setJWTCookie(returnTo: string, res: Response, req: Request) {
     maxAge: new Date(
       new Date().setFullYear(new Date().getFullYear() + 1),
     ).getTime(),
+    // pizzas rely on staging API for auth (due to static redirect URIs), so we have to allow cross-site
     sameSite: "none",
     secure: true,
   };

api.planx.uk/modules/auth/middleware.ts

@@ -8,7 +8,7 @@ import type { Authenticator } from "passport";
 import type { RequestHandler } from "http-proxy-middleware";
 import type { Role } from "@opensystemslab/planx-core/types";
 import { AsyncLocalStorage } from "async_hooks";
-import type { Request } from "express";
+import type { CookieOptions, Request } from "express";
 
 export const userContext = new AsyncLocalStorage<{ user: Express.User }>();
 
@@ -136,15 +136,27 @@ export const getMicrosoftAuthHandler = (
   return (req, res, next) => {
     req.session!.returnTo = req.get("Referrer");
 
-    // generate a nonce to enable us to validate the response from OP
+    // generate a nonce to enable us to validate the response from OP (mitigates against CSRF attacks)
     const nonce = generators.nonce();
     console.debug(`Generated a nonce: %s`, nonce);
-    req.session!.nonce = nonce;
 
-    // @ts-expect-error (method not typed to accept nonce, but it does pass it to the strategy)
+    // we hash the nonce to avoid sending it plaintext over the wire in our auth request
+    const hash = crypto.createHash("sha256").update(nonce).digest("hex");
+    console.debug(`Hashed nonce: %s`, hash);
+
+    // we store the original nonce in a short-lived, httpOnly but cross-site cookie
+    const httpOnlyCookieOptions: CookieOptions = {
+      maxAge: 15 * 60 * 1000, // 15 mins
+      sameSite: "none",
+      httpOnly: true,
+      secure: true,
+    };
+    res.cookie("ms-oidc-nonce", nonce, httpOnlyCookieOptions);
+
+    // @ts-expect-error (method not typed to accept nonce, but it does include it in the request)
     return passport.authenticate("microsoft-oidc", {
       prompt: "select_account",
-      nonce,
+      nonce: hash,
     })(req, res, next);
   };
 };

api.planx.uk/modules/auth/strategy/microsoft-oidc.ts

@@ -1,3 +1,4 @@
+import crypto from "crypto";
 import type {
   Client,
   ClientMetadata,
@@ -41,18 +42,30 @@ export const getMicrosoftOidcStrategy = (client: Client): Strategy<Client> => {
 };
 
 const verifyCallback: StrategyVerifyCallbackReq<Express.User> = async (
-  req: Http.IncomingMessageWithSession,
+  req: Http.IncomingMessageWithCookies,
   tokenSet,
   done,
 ): Promise<void> => {
   // TODO: use tokenSet.state to pass the redirectTo query param through the auth flow
+  // TODO: validate id_token sig with the public key from the jwks_uri (...v2.0/keys)
   const claims: IdTokenClaims = tokenSet.claims();
-  const email = claims.email;
-  const returned_nonce = claims.nonce;
 
-  if (returned_nonce != req.session?.nonce) {
-    return done(new Error("Returned nonce does not match session nonce"));
+  // ensure the response is authentic by comparing nonce
+  const returned_nonce = claims.nonce;
+  if (!req.cookies || !req.cookies["ms-oidc-nonce"]) {
+    return done(new Error("No nonce found in appropriate cookie"));
   }
+  const original_nonce = req.cookies["ms-oidc-nonce"];
+  const hash = crypto.createHash("sha256").update(original_nonce).digest("hex");
+  if (returned_nonce != hash) {
+    return done(
+      new Error(
+        "Returned nonce does not match nonce sent with original request",
+      ),
+    );
+  }
+
+  const email = claims.email;
   if (!email) {
     return done(new Error("Unable to authenticate without email"));
   }

api.planx.uk/modules/flows/validate/controller.ts

@@ -22,7 +22,9 @@ export type ValidateAndDiffFlowController = ValidatedRequestHandler<
 >;
 
 export const validateAndDiffFlowController: ValidateAndDiffFlowController =
-  async (_req, res, next) => {
+  async (req, res, next) => {
+    req.setTimeout(120 * 1000); // Temporary bump to address large diff timeouts
+
     try {
       const { flowId } = res.locals.parsedReq.params;
       const result = await validateAndDiffFlow(flowId);

api.planx.uk/package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@airbrake/node": "^2.1.8",
-    "@opensystemslab/planx-core": "git+https://github.com/theopensystemslab/planx-core#54be9e0",
+    "@opensystemslab/planx-core": "git+https://github.com/theopensystemslab/planx-core#d3d933c",
     "@types/isomorphic-fetch": "^0.0.36",
     "adm-zip": "^0.5.10",
     "aws-sdk": "^2.1467.0",

api.planx.uk/server.ts

@@ -112,7 +112,8 @@ assert(process.env.UNIFORM_SUBMISSION_URL);
 // needed for storing original URL to redirect to in login flow
 app.use(
   cookieSession({
-    maxAge: 24 * 60 * 60 * 100,
+    // we don't need session to persist for long - it's only required for auth flow
+    maxAge: 2 * 60 * 60 * 1000, // 2hrs
     name: "session",
     secret: process.env.SESSION_SECRET,
   }),
@@ -198,9 +199,9 @@ declare global {
   }
 
   namespace Http {
-    interface IncomingMessageWithSession extends IncomingMessage {
-      session?: {
-        nonce: string;
+    interface IncomingMessageWithCookies extends IncomingMessage {
+      cookies?: {
+        "ms-oidc-nonce": string;
       };
     }
   }

doc/architecture/decisions/0003-testing-approach.md

@@ -1,4 +1,4 @@
-# 1. Testing Principles
+# 3. Testing Principles
 
 ## Status
 

doc/architecture/decisions/0008-authentication-with-microsoft.md

@@ -0,0 +1,48 @@
+# 8. User authentication via Microsoft SSO
+
+Date: 2024-10-31
+
+## Status
+
+Accepted
+
+## Context
+
+Previously, PlanX users could only log in to the editor using Google single sign on (SSO). This was true for OSL devs and end-users alike. Most councils run Microsoft, so we needed to add an additional option to authenticate via Microsoft instead.
+
+## Decisions
+
+We considered replacing the auth business logic wholesale with AWS Cognito, but this seemed like it would be a much more significant overhaul as compared with simply adding a new `passportjs` '[strategy](https://www.passportjs.org/concepts/authentication/strategies/)'.
+
+Since we already had a model strategy for Google, a principle decision which guided this work was to build a strategy for Microsoft which had parity with that existing solution. This also meant leveraging the existing method for a user to identify themselves to the client/editor, which is for the API to return a persistent `jwt` cookie after auth.
+
+### `passportjs`
+
+We considered a few strategies: [`passport-microsoft`](https://www.passportjs.org/packages/passport-microsoft/) didn't pass muster and [`passport-azure-ad`](https://www.passportjs.org/packages/passport-azure-ad/) was [deprecated](https://github.com/AzureAD/microsoft-identity-web/discussions/2405) (without replacement) by Microsoft, so we opted for building a custom solution using [OpenID Connect](https://openid.net/) (aka. OIDC, a layer on top of OAuth2 for which Microsoft has [good documentation](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc)) with the [certified](https://openid.net/developers/certified-openid-connect-implementations/) [`openid-client`](https://www.passportjs.org/packages/openid-client/) strategy.
+
+### Auth flow
+
+OIDC provides for multiple '[authorisation flows](https://auth0.com/docs/get-started/authentication-and-authorization-flow)'. In our case the frontend, which is a public client, directs users to the API for auth purposes, which can store secrets. This enables us to use Hybrid Flow, rather than the more cumbersome Authorization Code Flow.
+
+### Logging out
+
+We also considered what happens when users who have authenticated via Microsoft SSO log out, either from PlanX, or from their Microsoft account more widely.
+
+In the former case, we simply delete the `jwt` as usual. For the latter case, there was the option of implementing a [front channel logout URL](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc#what-is-a-front-channel-logout-url). Given the current setup, integrating this feature would have required a significant amount of work, and would also move us beyond parity with the Google solution, so we didn't deem it necessary at this time.
+
+## Consequences
+
+The upshot is that both devs and end-users can log into PlanX with any Microsoft email address (whether personal or belonging to/managed by an organisation).
+
+### ESM adoption
+
+With the implementationd described above, the API server has to fetch the [Microsoft OIDC config](https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration) on boot, which it does asynchronously. Observing this functionality would have required us to either refactor the codebase extensively, or write a [top-level](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top_level_await) `await`.
+
+The latter is much simpler and more elegant, but in turn requires that the API codebase is entirely ESM-compliant. This turned out to be a significant spike. Without going into detail, it prompted us to do the following (inter alia):
+
+- replace `ts-node-dev` with `tsx`
+- enforce the `verbatimModuleSyntax` [tsconfig option](https://www.typescriptlang.org/tsconfig/#verbatimModuleSyntax)
+- migrate our testing framework from Jest to Vitest
+- bump `passportjs` to latest version (a longstanding ticket)
+
+The happy byproduct of all this is a much more modern configuration of the API TypeScript setup, testing suite and dev framework.

doc/how-to/how-to-setup-azure-application.md

@@ -0,0 +1,19 @@
+# How to setup Azure application for Microsoft OIDC
+
+## Context
+
+One of the more complicated aspects of implementing the Microsoft single sign on via OpenID Connect (see ADR#0008) is setting up an appropriate application on Azure (Microsoft's cloud platform).
+
+We document the process here for posterity/future reproducibility.
+
+## Process 
+
+1. Start a new registration in the [App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) panel (this will automatically create a corresponding [Enterprise application](https://portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview))
+2. We will support account types ‘in any organizational directory’ (i.e. multitenant), *and* personal accounts
+3. Register the application as an SPA, with the following redirect URIs:
+    -  `https://api.editor.planx.uk/auth/microsoft/callback` (production)
+    -  `https://api.editor.planx.dev/auth/microsoft/callback` (staging)
+    -  `http://localhost/auth/microsoft/callback` (local development)
+3. Navigate to *Manage/Authentication*, and allow both access and ID tokens
+4. Go to *Manage/Certificates and secrets*, add a new client secret, and record the value - this is your `MICROSOFT_CLIENT_SECRET` environment variable
+5. Go to *Overview*, and copy the `Application (client) ID` - this is your `MICROSOFT_CLIENT_ID`

e2e/tests/api-driven/package.json

@@ -7,7 +7,7 @@
   "packageManager": "[email protected]",
   "dependencies": {
     "@cucumber/cucumber": "^9.3.0",
-    "@opensystemslab/planx-core": "git+https://github.com/theopensystemslab/planx-core#54be9e0",
+    "@opensystemslab/planx-core": "git+https://github.com/theopensystemslab/planx-core#d3d933c",
     "axios": "^1.7.4",
     "dotenv": "^16.3.1",
     "dotenv-expand": "^10.0.0",