[api] add Microsoft strategy to auth module (single sign-on)

.env.example

@@ -16,6 +16,10 @@ SESSION_SECRET=👻
 GOOGLE_CLIENT_ID=👻
 GOOGLE_CLIENT_SECRET=👻
 
+# Microsoft Azure OIDC credentials
+MICROSOFT_CLIENT_ID=👻
+MICROSOFT_CLIENT_SECRET=👻
+
 # AWS credentials for uploading user files from local and pull request environments to a staging S3 bucket
 AWS_S3_REGION=eu-west-2
 AWS_S3_ACL=public-read

api.planx.uk/.env.test.example

@@ -8,6 +8,9 @@ SESSION_SECRET=👻
 GOOGLE_CLIENT_ID=👻
 GOOGLE_CLIENT_SECRET=👻
 
+MICROSOFT_CLIENT_ID=👻
+MICROSOFT_CLIENT_SECRET=👻
+
 # AWS infrastructure
 AWS_S3_REGION=eu-west-2
 AWS_S3_BUCKET=👻

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

@@ -8,6 +8,7 @@ export const failedLogin: RequestHandler = (_req, _res, next) =>
   });
 
 export const logout: RequestHandler = (req, res) => {
+  // TODO: implement dual purpose as Microsoft frontend logout channel
   req.logout(() => {
     // do nothing
   });

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

@@ -3,9 +3,8 @@ import assert from "assert";
 import { ServerError } from "../../errors/index.js";
 import { Template } from "../../lib/notify/index.js";
 import { expressjwt } from "express-jwt";
-
-import passport from "passport";
-
+import { generators } from "openid-client";
+import { Authenticator } from "passport";
 import { RequestHandler } from "http-proxy-middleware";
 import { Role } from "@opensystemslab/planx-core/types";
 import { AsyncLocalStorage } from "async_hooks";
@@ -110,17 +109,54 @@ export const useJWT = expressjwt({
   getToken: getToken,
 });
 
-export const useGoogleAuth: RequestHandler = (req, res, next) => {
-  req.session!.returnTo = req.get("Referrer");
-  return passport.authenticate("google", {
-    scope: ["profile", "email"],
-  })(req, res, next);
+export const getGoogleAuthHandler = (
+  passport: Authenticator,
+): RequestHandler => {
+  return (req, res, next) => {
+    req.session!.returnTo = req.get("Referrer");
+    return passport.authenticate("google", {
+      scope: ["profile", "email"],
+    })(req, res, next);
+  };
+};
+
+export const getGoogleCallbackAuthHandler = (
+  passport: Authenticator,
+): RequestHandler => {
+  return (req, res, next) => {
+    return passport.authenticate("google", {
+      failureRedirect: "/auth/login/failed",
+    })(req, res, next);
+  };
+};
+
+export const getMicrosoftAuthHandler = (
+  passport: Authenticator,
+): RequestHandler => {
+  return (req, res, next) => {
+    req.session!.returnTo = req.get("Referrer");
+
+    // generate a nonce to enable us to validate the response from OP
+    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)
+    return passport.authenticate("microsoft-oidc", {
+      prompt: "select_account",
+      nonce,
+    })(req, res, next);
+  };
 };
 
-export const useGoogleCallbackAuth: RequestHandler = (req, res, next) => {
-  return passport.authenticate("google", {
-    failureRedirect: "/auth/login/failed",
-  })(req, res, next);
+export const getMicrosoftCallbackAuthHandler = (
+  passport: Authenticator,
+): RequestHandler => {
+  return (req, res, next) => {
+    return passport.authenticate("microsoft-oidc", {
+      failureRedirect: "/auth/login/failed",
+    })(req, res, next);
+  };
 };
 
 type UseRoleAuth = (authRoles: Role[]) => RequestHandler;

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

@@ -0,0 +1,40 @@
+import { Issuer } from "openid-client";
+import type { Authenticator } from "passport";
+import passport from "passport";
+
+import { googleStrategy } from "./strategy/google.js";
+import {
+  getMicrosoftOidcStrategy,
+  getMicrosoftClientConfig,
+  MICROSOFT_OPENID_CONFIG_URL,
+} from "./strategy/microsoft-oidc.js";
+
+export default async (): Promise<Authenticator> => {
+  // explicitly instantiate new passport class for clarity
+  const customPassport = new passport.Passport();
+
+  // instantiate Microsoft OIDC client, and use it to build the related strategy
+  const microsoftIssuer = await Issuer.discover(MICROSOFT_OPENID_CONFIG_URL);
+  console.debug("Discovered issuer %s", microsoftIssuer.issuer);
+  const microsoftOidcClient = new microsoftIssuer.Client(
+    getMicrosoftClientConfig(),
+  );
+  console.debug("Built Microsoft client: %O", microsoftOidcClient);
+  customPassport.use(
+    "microsoft-oidc",
+    getMicrosoftOidcStrategy(microsoftOidcClient),
+  );
+
+  // note that we don't serialize the user in any meaningful way - we just store the entire jwt in session
+  // i.e. req.session.passport.user == { jwt: "..." }
+  customPassport.use("google", googleStrategy);
+  customPassport.serializeUser((user: Express.User, done) => {
+    done(null, user);
+  });
+  customPassport.deserializeUser((user: Express.User, done) => {
+    done(null, user);
+  });
+
+  // tsc dislikes the use of 'this' in the passportjs codebase, so we cast explicitly
+  return customPassport as Authenticator;
+};

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

@@ -1,16 +1,26 @@
 import { Router } from "express";
+import type { Authenticator } from "passport";
 import * as Middleware from "./middleware.js";
 import * as Controller from "./controller.js";
 
-const router = Router();
+export default (passport: Authenticator): Router => {
+  const router = Router();
 
-router.get("/logout", Controller.logout);
-router.get("/auth/login/failed", Controller.failedLogin);
-router.get("/auth/google", Middleware.useGoogleAuth);
-router.get(
-  "/auth/google/callback",
-  Middleware.useGoogleCallbackAuth,
-  Controller.handleSuccess,
-);
+  router.get("/logout", Controller.logout);
+  // router.get("/auth/frontchannel-logout", Controller.frontChannelLogout)
+  router.get("/auth/login/failed", Controller.failedLogin);
+  router.get("/auth/google", Middleware.getGoogleAuthHandler(passport));
+  router.get(
+    "/auth/google/callback",
+    Middleware.getGoogleCallbackAuthHandler(passport),
+    Controller.handleSuccess,
+  );
+  router.get("/auth/microsoft", Middleware.getMicrosoftAuthHandler(passport));
+  router.post(
+    "/auth/microsoft/callback",
+    Middleware.getMicrosoftCallbackAuthHandler(passport),
+    Controller.handleSuccess,
+  );
 
-export default router;
+  return router;
+};

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

@@ -0,0 +1,66 @@
+import type { TokenSet, Client, ClientMetadata } from "openid-client";
+import { Strategy } from "openid-client";
+import { buildJWT } from "../service.js";
+
+export const MICROSOFT_OPENID_CONFIG_URL =
+  "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration";
+
+export const getMicrosoftClientConfig = (): ClientMetadata => {
+  const client_id = process.env.MICROSOFT_CLIENT_ID!;
+  if (typeof client_id !== "string") {
+    throw new Error("No MICROSOFT_CLIENT_ID in the environment");
+  }
+  return {
+    client_id,
+    client_secret: process.env.MICROSOFT_CLIENT_SECRET!,
+    redirect_uris: [`${process.env.API_URL_EXT}/auth/microsoft/callback`],
+    post_logout_redirect_uris: [process.env.EDITOR_URL_EXT!],
+    response_types: ["id_token"],
+  };
+};
+
+// oidc = OpenID Connect, an auth standard built on top of OAuth 2.0
+export const getMicrosoftOidcStrategy = (client: Client): Strategy<Client> => {
+  return new Strategy(
+    {
+      client: client,
+      params: {
+        scope: "openid email profile",
+        response_mode: "form_post",
+      },
+      // need the request in the verify callback to validate the returned nonce
+      passReqToCallback: true,
+    },
+    async (req: any, tokenSet: TokenSet, done: any): Promise<void> => {
+      // TODO: use tokenSet.state to pass the redirectTo query param through the auth flow
+      const claims = 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"),
+          null,
+        );
+      }
+
+      if (!email) {
+        return done(new Error("Unable to authenticate without email"), null);
+      }
+
+      const jwt = await buildJWT(email);
+
+      if (!jwt) {
+        return done(
+          {
+            status: 404,
+            message: `User (${email}) not found. Do you need to log in to a different Microsoft Account?`,
+          } as any,
+          null,
+        );
+      }
+
+      return done(null, { jwt });
+    },
+  );
+};

api.planx.uk/package.json

@@ -45,6 +45,7 @@
     "multer": "^1.4.5-lts.1",
     "nanoid": "^3.3.7",
     "notifications-node-client": "^8.2.0",
+    "openid-client": "^5.6.5",
     "passport": "^0.7.0",
     "passport-google-oauth20": "^2.0.0",
     "pino-noir": "^2.2.1",

api.planx.uk/server.ts

@@ -10,15 +10,14 @@ import pinoLogger from "express-pino-logger";
 import helmet from "helmet";
 import { Server } from "http";
 import "isomorphic-fetch";
-import passport from "passport";
 import noir from "pino-noir";
 import airbrake from "./airbrake.js";
 import { useSwaggerDocs } from "./docs/index.js";
 import { ServerError } from "./errors/index.js";
 import adminRoutes from "./modules/admin/routes.js";
 import analyticsRoutes from "./modules/analytics/routes.js";
-import authRoutes from "./modules/auth/routes.js";
-import { googleStrategy } from "./modules/auth/strategy/google.js";
+import getPassport from "./modules/auth/passport.js";
+import getAuthRoutes from "./modules/auth/routes.js";
 import fileRoutes from "./modules/file/routes.js";
 import flowRoutes from "./modules/flows/routes.js";
 import gisRoutes from "./modules/gis/routes.js";
@@ -122,19 +121,16 @@ app.use(
 // register stubs after cookieSession middleware initialisation
 app.use(registerSessionStubs);
 
-passport.use("google", googleStrategy);
-
-passport.serializeUser(function (user, cb) {
-  cb(null, user);
-});
-
-passport.deserializeUser(function (obj: Express.User, cb) {
-  cb(null, obj);
-});
+// equip passport with auth strategies early on, so we can pass it to route handlers
+const passport = await getPassport();
 app.use(passport.initialize());
 app.use(passport.session());
+
 app.use(bodyParser.urlencoded({ extended: true }));
 
+// auth routes rely on the passport class we've just initialised
+const authRoutes = await getAuthRoutes(passport);
+
 // Setup API routes
 app.use(adminRoutes);
 app.use(analyticsRoutes);

api.planx.uk/tsconfig.json

@@ -15,7 +15,7 @@
     "strict": true,
     "target": "esnext",
     "types": ["vitest/globals"],
-    // ensure the code is ready for transpilation by tsx/esbuild (used in dev)
+    // ensure the code is ready for per-file transpilation by tsx (used in dev mode)
     "isolatedModules": true,
     // TODO: implement "verbatimModuleSyntax" option (laborious)
   },