Feature: add facility in config to add <Extensions> element in SAML request

.mocharc.json

@@ -1,10 +1,10 @@
 {
   "diff": true,
-  "extension": "spec.ts",
+  "extension": ".ts",
   "package": "./package.json",
   "recursive": true,
   "reporter": "spec",
   "require": ["choma", "ts-node/register"],
-  "files": "test/**/*.spec.ts",
-  "watch-files": "test/**/*.spec.ts"
+  "files": "test/**/*.[spec|test].ts",
+  "watch-files": "test/**/*.[spec|test].ts"
 }

README.md

@@ -101,6 +101,26 @@ const saml = new SAML(options);
 - `additionalLogoutParams`: dictionary of additional query params to add to 'logout' requests
 - `logoutCallbackUrl`: The value with which to populate the `Location` attribute in the `SingleLogoutService` elements in the generated service provider metadata.
 
+- **SAML Extensions**
+- `samlExtensions`: Optional, The SAML extension provides a more flexible structure for expressing which combination of Attributes are requested by service providers in comparison to the existing mechanisms, [More about extensions](https://docs.oasis-open.org/security/saml-protoc-req-attr-req/v1.0/saml-protoc-req-attr-req-v1.0.html). There are many possible values for the `samlExtensions` element. It accepts fully customize [XMLBuilder](https://www.npmjs.com/package/xmlbuilder) type.
+
+```javascript
+// Example
+samlExtensions: {
+  "md:RequestedAttribute": {
+    "@isRequired": "true",
+    "@Name": "Lastname",
+    "@xmlns:md": "urn:oasis:names:tc:SAML:2.0:metadata"
+  },
+  vetuma: {
+    "@xmlns": "urn:vetuma:SAML:2.0:extensions",
+    LG: {
+      "#text": "sv",
+    },
+  },
+},
+```
+
 ### generateServiceProviderMetadata( decryptionCert, signingCert )
 
 As a convenience, the strategy object exposes a `generateServiceProviderMetadata` method which will generate a service provider metadata document suitable for supplying to an identity provider. This method will only work on strategies which are configured with a `callbackUrl` (since the relative path for the callback is not sufficient information to generate a complete metadata document).

src/saml.ts

@@ -27,7 +27,7 @@ import {
   XMLOutput,
 } from "./types";
 import { AuthenticateOptions, AuthorizeOptions } from "./passport-saml-types";
-import { assertRequired } from "./utility";
+import { assertRequired, validateSAMLExtensionsElement } from "./utility";
 import {
   buildXml2JsObject,
   buildXmlBuilderObject,
@@ -265,6 +265,16 @@ class SAML {
       request["samlp:AuthnRequest"]["@AssertionConsumerServiceURL"] = this.getCallbackUrl(host);
     }
 
+    const samlExtensions = this.options.samlExtensions;
+    if (samlExtensions != null) {
+      if (validateSAMLExtensionsElement(samlExtensions)) {
+        request["samlp:AuthnRequest"]["samlp:Extensions"] = {
+          "@xmlns:samlp": "urn:oasis:names:tc:SAML:2.0:protocol",
+          ...samlExtensions,
+        };
+      }
+    }
+
     if (this.options.identifierFormat != null) {
       request["samlp:AuthnRequest"]["samlp:NameIDPolicy"] = {
         "@xmlns:samlp": "urn:oasis:names:tc:SAML:2.0:protocol",

src/types.ts

@@ -123,6 +123,7 @@ export interface SamlOptions extends Partial<SamlSigningOptions>, MandatorySamlO
 
   // extras
   disableRequestAcsUrl: boolean;
+  samlExtensions?: any;
 }
 
 export interface StrategyOptions {
@@ -157,3 +158,12 @@ export class ErrorWithXmlStatus extends Error {
     super(message);
   }
 }
+
+/**
+ * XML Schema Error on JSON Data
+ */
+export class JSONXMLSchemaError extends Error {
+  constructor(message: string) {
+    super(message);
+  }
+}

src/utility.ts

@@ -1,5 +1,6 @@
 import { SamlSigningOptions } from "./types";
 import { signXml } from "./xml";
+import { JSONXMLSchemaError } from "./types";
 
 export function assertRequired<T>(value: T | null | undefined, error?: string): T {
   if (value === undefined || value === null || (typeof value === "string" && value.length === 0)) {
@@ -20,3 +21,61 @@ export function signXmlResponse(samlMessage: string, options: SamlSigningOptions
     options
   );
 }
+
+export function assertObjectAndNotEmpty(value: any, error?: string): any {
+  if (typeof value !== "object" || JSON.stringify(value) === JSON.stringify({})) {
+    throw new TypeError(error ?? "value does not exist");
+  } else {
+    return value;
+  }
+}
+
+export function validateSAMLExtensionsElement(jsonSAMLExtensionsElement: any): boolean {
+  jsonSAMLExtensionsElement = assertObjectAndNotEmpty(
+    jsonSAMLExtensionsElement,
+    `samlExtensions Element value should be object and not empty`
+  );
+  let result = true;
+  for (const subElementKey in jsonSAMLExtensionsElement) {
+    if (!validateXMLNamespace(subElementKey, jsonSAMLExtensionsElement[subElementKey])) {
+      result = false;
+      break;
+    }
+  }
+  return result;
+}
+
+/**
+ * Validate the XMLBuilder input JSON, wether it has proper namespece or not
+ * @param jsonXMLElementKey - Key of the element, need key to understand its namespace
+ * @param jsonXMLElement - Just JSON which we want to pass to xmlbuilder to make xml
+ * @returns boolean | JSONXMLSchemaError
+ */
+export function validateXMLNamespace(
+  jsonXMLElementKey: string,
+  jsonXMLElementValue: any
+): boolean | JSONXMLSchemaError {
+  jsonXMLElementKey = assertRequired(jsonXMLElementKey, `key should be defined`);
+
+  jsonXMLElementValue = assertObjectAndNotEmpty(
+    jsonXMLElementValue,
+    `${jsonXMLElementKey} XML Element value should be object and not empty`
+  );
+
+  // check namespace attribute
+  const elementKeyParts = jsonXMLElementKey.split(":");
+  let namespaceKey;
+  if (elementKeyParts && elementKeyParts.length > 1) {
+    const elementKeyPrefix = elementKeyParts[0];
+    namespaceKey = `@xmlns:${elementKeyPrefix}`;
+  } else {
+    namespaceKey = "@xmlns";
+  }
+  const namespaceValue = jsonXMLElementValue[namespaceKey];
+  if (!namespaceValue) {
+    throw new JSONXMLSchemaError(
+      `Namespace ${namespaceKey} is not defined for element ${jsonXMLElementKey}`
+    );
+  }
+  return true;
+}

test/samlRequest.spec.ts

@@ -0,0 +1,127 @@
+import { SAML } from "../src/saml";
+import { FAKE_CERT, SamlCheck } from "./types";
+import * as zlib from "zlib";
+import * as should from "should";
+import { parseString } from "xml2js";
+
+const capturedSamlRequestChecks: SamlCheck[] = [
+  {
+    name: "Config with Extensions",
+    config: {
+      entryPoint: "https://wwwexampleIdp.com/saml",
+      cert: FAKE_CERT,
+      samlExtensions: {
+        "md:RequestedAttribute": {
+          "@isRequired": "true",
+          "@Name": "Lastname",
+          "@xmlns:md": "urn:oasis:names:tc:SAML:2.0:metadata",
+        },
+        vetuma: {
+          "@xmlns": "urn:vetuma:SAML:2.0:extensions",
+          LG: {
+            "#text": "sv",
+          },
+        },
+      },
+    },
+    result: {
+      "samlp:AuthnRequest": {
+        $: {
+          "xmlns:samlp": "urn:oasis:names:tc:SAML:2.0:protocol",
+          Version: "2.0",
+          ProtocolBinding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
+          AssertionConsumerServiceURL: "http://localhost/saml/consume",
+          Destination: "https://wwwexampleIdp.com/saml",
+        },
+        "saml:Issuer": [
+          { _: "onelogin_saml", $: { "xmlns:saml": "urn:oasis:names:tc:SAML:2.0:assertion" } },
+        ],
+        "samlp:Extensions": [
+          {
+            $: {
+              "xmlns:samlp": "urn:oasis:names:tc:SAML:2.0:protocol",
+            },
+            "md:RequestedAttribute": [
+              {
+                $: {
+                  isRequired: "true",
+                  Name: "Lastname",
+                  "xmlns:md": "urn:oasis:names:tc:SAML:2.0:metadata",
+                },
+              },
+            ],
+            vetuma: [
+              {
+                $: { xmlns: "urn:vetuma:SAML:2.0:extensions" },
+                LG: ["sv"],
+              },
+            ],
+          },
+        ],
+        "samlp:NameIDPolicy": [
+          {
+            $: {
+              "xmlns:samlp": "urn:oasis:names:tc:SAML:2.0:protocol",
+              Format: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+              AllowCreate: "true",
+            },
+          },
+        ],
+        "samlp:RequestedAuthnContext": [
+          {
+            $: { "xmlns:samlp": "urn:oasis:names:tc:SAML:2.0:protocol", Comparison: "exact" },
+            "saml:AuthnContextClassRef": [
+              {
+                _: "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport",
+                $: { "xmlns:saml": "urn:oasis:names:tc:SAML:2.0:assertion" },
+              },
+            ],
+          },
+        ],
+      },
+    },
+  },
+];
+
+describe("SAML request", function () {
+  function testForCheck(check: SamlCheck) {
+    return function (done: Mocha.Done) {
+      function helper(err: Error | null, samlRequest: Buffer) {
+        try {
+          should.not.exist(err);
+          parseString(samlRequest.toString(), function (err, doc) {
+            try {
+              should.not.exist(err);
+              delete doc["samlp:AuthnRequest"]["$"]["ID"];
+              delete doc["samlp:AuthnRequest"]["$"]["IssueInstant"];
+              doc.should.eql(check.result);
+              done();
+            } catch (err2) {
+              done(err2);
+            }
+          });
+        } catch (err3) {
+          done(err3);
+        }
+      }
+      const oSAML = new SAML(check.config);
+      oSAML.getAuthorizeFormAsync("http://localhost/saml/consume").then((formBody) => {
+        formBody.should.match(/<!DOCTYPE html>[^]*<input.*name="SAMLRequest"[^]*<\/html>/);
+        const samlRequestMatchValues = formBody.match(/<input.*name="SAMLRequest" value="([^"]*)"/);
+        const encodedSamlRequest = samlRequestMatchValues && samlRequestMatchValues[1];
+
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const buffer = Buffer.from(encodedSamlRequest!, "base64");
+        if (check.config.skipRequestCompression) {
+          return helper(null, buffer);
+        } else {
+          return zlib.inflateRaw(buffer, helper);
+        }
+      });
+    };
+  }
+
+  capturedSamlRequestChecks.forEach(function (check) {
+    it(check.name, testForCheck(check));
+  });
+});