Introduce extensible secure form submissions pattern

Introduce APIM support

Author: Dashue

docs/runner/msal-apim-authentication.md

@@ -0,0 +1,23 @@
+# Microsoft Authentication Layer (MSAL) APIM Authentication Support
+
+The `MsalAuthorizer` service supports MSAL authentication to communicate securely with APIM-hosted API services.
+
+## Setup
+
+To use MSAL Authentication you will need to configure the following environment variables:
+
+| Variable name   | Definition                                     | Example                            |
+| --------------- | ---------------------------------------------- | ---------------------------------- |
+| `APIM_BASE_URL` | The base URL of the APIM hosted service        | `https://apim.example.com`         |
+| `TENANT_ID`     | Azure AD tenant ID for MSAL authentication     | `tenant-id`                        |
+| `CLIENT_ID`     | Azure AD client ID for MSAL authentication     | `client-id`                        |
+| `CLIENT_SECRET` | Azure AD client secret for MSAL authentication | `client-secret`                    |
+| `SCOPES`        | MSAL scopes required to access the service     | `["https://example.com/.default"]` |
+
+## Multi-tenant support
+
+Multi-tenancy is supported for each form IoC registration. Each form registers its own APIM hosted service dependencies with their respective `MsalAuthorizerConfig`, which includes its own MSAL credentials. Through this approach there is no shared state between forms or service instances on a form, so forms on the same deployed server can authenticate against different tenants independently.
+
+## Token lifecycle
+
+Authentication is handled by `MsalAuthorizer`, which uses the MSAL package's `acquireTokenByClientCredential`. MSAL caches tokens internally and reuses them until expiry (or at least near expiry), so there is no network call to the identity provider on every invocation. Token refresh is also handled automatically by MSAL, so no additional retry or refresh logic is needed.

docs/runner/secure-form-submissions.md

@@ -0,0 +1,81 @@
+# Secure Form Submissions
+
+This feature allows the user to achieve secure form submissions through the addition of security headers
+
+## Form Configuration
+
+The configuration inherits the `MsalAuthorizerConfig`  
+Refer to the [`MSAL Authentication documentation`](/docs/runner/msal-apim-authentication.md) for information about `tenantId`, `clientId`, `clientSecret` and `scopes`
+
+```json
+"secureFormSubmissionConfig": {
+    "tenantId": "${env_form_submission_tenant_id}",
+    "clientId": "${env_form_submission_client_id}",
+    "clientSecret": "${env_form_submission_client_secret}",
+    "scopes": ["${env_form_submission_scope1}", "${env_form_submission_scope2}"],
+    "useAwsWafUserAgentWorkaround": boolean
+  }
+```
+
+> **Note: useAwsWafUserAgentWorkaround**  
+> AWS WAF requires User-Agent to be present as part of auth, setting this option to tru will make the functioality provide one to prevent 403
+
+## How to Update env variables
+
+Environment variables can be added or updated by following the guide at <https://ukhsa.atlassian.net/wiki/spaces/IDT/pages/294420993/XGO-007+Adding+New+Environment+Variables>
+
+## How it works
+
+### The following is a top-down view
+
+The [`FormSecurityService`](/runner/src/server/services/formSecurityService.ts) supports our different security mechanisms.
+
+- For the [`webhookHmacSharedKey`](/runner/src/server/services/formSecurityService.ts#L31) approach it generates Hmac and sets HMAC specific headers.
+
+- For the [`APIM`](/runner/src/server/services/formSecurityService.ts#L49) approach it uses server Dependency Injection to register named instances of [`SecureFormSubmissionService`](/runner/src/server/services/secureFormSubmissionService.ts#L137) which exposes a `getAuthHeader` method that returns an object in the form of `{ Authorization: "Bearer <token>"}`.  
+  Registration into DI is done on [`server initialization`](/runner/src/server/index.ts#L191) for forms declaring the `secureFormSubmissionConfig`
+
+The `StatusService` [`invokes`](/runner/src/server/services/statusService.ts#L137) `FormSecurityService.getSecurityHeaders` method which returns headers based on what approach the form use. It then passes those headers to the `WebhookService`
+
+The `WebhookService` accepts [`additionalHeaders?: Record<string, string>`](/runner/src/server/services/webhookService.ts#L32) as part of it's postRequest method, which it then includes when it makes the request to the form configured webhook output.
+
+### Implementation Details: DI service registration
+
+Per form SecureFormSubmissionService registration
+
+```typescript
+for (const form of enginePlugin.options.configs) {
+  const formId = form.id;
+
+  if (form.configuration.secureFormSubmissionConfig) {
+    const instanceName = getSecureFormSubmissionServiceInstance(formId);
+
+    const namedService = new SecureFormSubmissionService(
+      form.configuration.secureFormSubmissionConfig
+    );
+
+    await server.registerService(
+      Schmervice.withName(instanceName, namedService)
+    );
+  }
+}
+```
+
+### Implementation Details: DI service resolution
+
+Once registered, the service can be resolved from the DI using the below.  
+Notice we have to do a dynamic resolution - since services are dynamically registered based on what forms are served, there is no knowledge of what services exists and in turn there's no way to statically type the access.
+
+```typescript
+const instanceName = getSecureFormSubmissionServiceInstance(formId);
+if (instanceName) {
+  const services = request.services([])
+
+  const serviceInstance = services[instanceName] as SecureFormSubmissionService;
+  if (serviceInstance) {
+    const headers = await serviceInstance.getAuthHeader();
+    ...
+  }
+  ....
+}
+```

model/src/data-model/types.ts

@@ -196,6 +196,18 @@ export type Analytics = {
   matomoUrl: string;
 };
 
+export interface MsalAuthorizerConfig {
+  tenantId: string;
+  clientId: string;
+  clientSecret: string;
+  scopes: string[];
+}
+
+export interface SecureFormSubmissionConfig extends MsalAuthorizerConfig {
+  /* Empty for now */
+  useAwsWafUserAgentWorkaround?: boolean;
+}
+
 /**
  * `FormDefinition` is a typescript representation of `Schema`
  */
@@ -232,4 +244,5 @@ export type FormDefinition = {
   serviceName?: string | undefined;
   confirmationSessionTimeout: number | undefined;
   returnTo?: boolean | undefined;
+  secureFormSubmissionConfig: SecureFormSubmissionConfig;
 };

model/src/schema/schema.ts

@@ -322,6 +322,19 @@ const exitSchema = joi.object().keys({
   format: joi.string().allow("STATE", "WEBHOOK"),
 });
 
+const msalAuthorizeConfigSchema = joi.object().keys({
+  tenantId: joi.string().required(),
+  clientId: joi.string().required(),
+  clientSecret: joi.string().required(),
+  scopes: joi.array().items(joi.string()).min(1).required(),
+});
+
+const secureFormSubmissionConfig = msalAuthorizeConfigSchema.concat(
+  joi.object().keys({
+    useAwsWafUserAgentWorkaround: joi.bool().optional(),
+  })
+);
+
 export const Schema = joi
   .object()
   .required()
@@ -365,6 +378,7 @@ export const Schema = joi
     serviceName: joi.string().optional(),
     confirmationSessionTimeout: joi.number().optional(),
     returnTo: joi.boolean().optional(),
+    secureFormSubmissionConfig: secureFormSubmissionConfig.optional(),
   });
 
 /**

runner/package.json

@@ -34,6 +34,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
+    "@azure/msal-node": "^5.2.1",
     "@babel/runtime": "^7.23.3",
     "@hapi/bell": "^13.0.1",
     "@hapi/boom": "^10.0.1",

runner/src/server/index.ts

@@ -34,6 +34,9 @@ import {
   MockUploadService,
   WebhookService,
   ExitService,
+  FormSecurityService,
+  SecureFormSubmissionService,
+  getSecureFormSubmissionServiceInstance,
 } from "./services";
 import { HapiRequest, HapiResponseToolkit, RouteConfig } from "./types";
 import getRequestInfo from "./utils/getRequestInfo";
@@ -116,6 +119,7 @@ async function createServer(routeConfig: RouteConfig) {
     WebhookService,
     AddressService,
     ExitService,
+    FormSecurityService,
   ]);
   if (!config.documentUploadApiUrl) {
     server.registerService([
@@ -173,6 +177,26 @@ async function createServer(routeConfig: RouteConfig) {
     return h.continue;
   });
 
+  const enginePlugin = configureEnginePlugin(
+    formFileName,
+    formFilePath,
+    options
+  );
+
+  for (const form of enginePlugin.options.configs) {
+    const formId = form.id;
+
+    if (form.configuration.secureFormSubmissionConfig) {
+      const instanceName = getSecureFormSubmissionServiceInstance(formId);
+      const namedService = new SecureFormSubmissionService(
+        form.configuration.secureFormSubmissionConfig
+      );
+      await server.registerService(
+        Schmervice.withName(instanceName, namedService)
+      );
+    }
+  }
+
   await server.register(pluginLocale);
   await server.register(pluginViews);
   await server.register(

runner/src/server/plugins/engine/configureEnginePlugin.ts

@@ -7,31 +7,14 @@ import {
 } from "./services/configurationService";
 import { idFromFilename } from "./helpers";
 import config from "../../config";
-
-type ConfigureEnginePlugin = (
-  formFileName?: string,
-  formFilePath?: string
-) => {
-  plugin: any;
-  options: {
-    modelOptions: {
-      relativeTo: string;
-      previewMode: any;
-    };
-    configs: {
-      configuration: any;
-      id: string;
-    }[];
-    previewMode: boolean;
-  };
-};
+import { FormDefinition } from "@xgovformbuilder/model";
 
 const relativeTo = __dirname;
 
 type EngineOptions = {
   previewMode?: boolean;
 };
-export const configureEnginePlugin: ConfigureEnginePlugin = (
+export const configureEnginePlugin = (
   formFileName,
   formFilePath,
   options?: EngineOptions
@@ -41,7 +24,10 @@ export const configureEnginePlugin: ConfigureEnginePlugin = (
   if (formFileName && formFilePath) {
     configs = [
       {
-        configuration: require(path.join(formFilePath, formFileName)),
+        configuration: require(path.join(
+          formFilePath,
+          formFileName
+        )) as FormDefinition,
         id: idFromFilename(formFileName),
       },
     ];

runner/src/server/plugins/engine/services/configurationService.ts

@@ -2,11 +2,12 @@ import fs from "fs";
 import path from "path";
 
 import { idFromFilename } from "../helpers";
+import { FormDefinition } from "@xgovformbuilder/model";
 
 const FORMS_FOLDER = path.join(__dirname, "..", "..", "..", "forms");
 
 export type FormConfiguration = {
-  configuration: any; // TODO
+  configuration: FormDefinition;
   id: string;
 };
 

runner/src/server/services/formSecurityService.ts

@@ -0,0 +1,82 @@
+import { HapiRequest, HapiServer } from "../types";
+import { createHmacRaw } from "../utils/hmac";
+import {
+  getSecureFormSubmissionServiceInstance,
+  SecureFormSubmissionService,
+} from "./secureFormSubmissionService";
+
+export class FormSecurityService {
+  /**
+   * Service responsible for securing form submissions. This service has been registered by {@link #createServer}
+   */
+
+  logger: HapiServer["logger"];
+  constructor(server) {
+    this.logger = server.logger;
+  }
+
+  async getSecurityHeaders(request: HapiRequest) {
+    const formId = request.params?.id as string;
+    if (!formId) {
+      return;
+    }
+
+    const form = request.server?.app?.forms?.[formId];
+    if (!form) {
+      return;
+    }
+
+    let customSecurityHeaders: Record<string, string> = {};
+
+    if (form.def.webhookHmacSharedKey) {
+      /**
+       * If the config contains the OPTIONAL webhookHmacSharedKey, then we send HMAC Auth headers
+       * This is used to confirm ONLY X-Gov's backend is sending data to our API
+       * Everyone else will be Rejected
+       * (Used by KLS)
+       */
+      const hmacKey = form.def.webhookHmacSharedKey;
+
+      const [hmacSignature, requestTime, hmacExpiryTime] = await createHmacRaw(
+        request.yar.id,
+        hmacKey
+      );
+      customSecurityHeaders = {
+        "X-Request-ID": request.yar.id.toString(),
+        "X-HMAC-Signature": hmacSignature.toString(),
+        "X-HMAC-Time": requestTime.toString(),
+      };
+    } else if (form.def.secureFormSubmissionConfig) {
+      /** Secure form submissions facilitated through a form specific instance of the secureFormSubmissionService
+       * We resolve the named service instance for the form
+       * If it exists, it's implementation will return a headers object \{ Authorization: "Bearer <Token>"\}
+       * For more information @see secure-form-submissions.md
+       */
+
+      const instanceName = getSecureFormSubmissionServiceInstance(formId);
+      if (instanceName) {
+        const serviceInstance = request.services([])[
+          instanceName
+        ] as SecureFormSubmissionService;
+
+        if (serviceInstance) {
+          const headers = await serviceInstance.getAuthHeader();
+          if (headers) {
+            const {
+              useAwsWafUserAgentWorkaround,
+            } = form.def.secureFormSubmissionConfig;
+
+            if (useAwsWafUserAgentWorkaround == true) {
+              /* AWS WAF forces User-Agent as part of auth, provide one to prevent 403 */
+              headers["User-Agent"] = "X-GOV Forms/v1.0";
+            }
+
+            customSecurityHeaders = headers;
+          }
+        }
+      }
+    }
+
+    return customSecurityHeaders;
+  }
+}

runner/src/server/services/index.ts

@@ -8,3 +8,9 @@ export { WebhookService } from "./webhookService";
 export { StatusService } from "./statusService";
 export { AddressService } from "./addressService";
 export { ExitService } from "./ExitService";
+export { FormSecurityService } from "./formSecurityService";
+export { MsalAuthorizer } from "./msalAuthorizerService";
+export {
+  SecureFormSubmissionService,
+  getSecureFormSubmissionServiceInstance,
+} from "./secureFormSubmissionService";