Refactor SAML response validation to use node-saml

Replaces custom SAML assertion validation logic with @node-saml/node-saml for signature, audience, and time validation. Updates error handling to map node-saml errors to SamlValidationError types, adds fallback error type, and removes now-unnecessary utility functions and tests. Extends and improves test coverage for SAML response parsing, error cases, and attribute extraction.

Author: neSpecc

src/sso/saml/service.ts

@@ -1,6 +1,7 @@
+import { SAML, SamlConfig as NodeSamlConfig, Profile } from '@node-saml/node-saml';
 import { SamlConfig, SamlResponseData } from '../types';
 import { SamlValidationError, SamlValidationErrorType } from './types';
-import { validateAudience, validateRecipient, validateTimeConditions } from './utils';
+import { extractAttribute } from './utils';
 
 /**
  * Service for SAML SSO operations
@@ -40,31 +41,172 @@ export default class SamlService {
    * @param workspaceId - workspace ID
    * @param acsUrl - expected Assertion Consumer Service URL
    * @param samlConfig - SAML configuration
+   * @param expectedRequestId - optional expected InResponseTo value (if provided, validates that response matches)
    * @returns parsed SAML response data
+   * @throws SamlValidationError if validation fails
    */
   public async validateAndParseResponse(
     samlResponse: string,
     workspaceId: string,
     acsUrl: string,
-    samlConfig: SamlConfig
+    samlConfig: SamlConfig,
+    expectedRequestId?: string
   ): Promise<SamlResponseData> {
+    const saml = this.createSamlInstance(acsUrl, samlConfig);
+
+    let profile: Profile;
+
+    try {
+      /**
+       * node-saml validates:
+       * - XML signature using x509Cert
+       * - Audience (via idpIssuer option)
+       * - Time conditions (NotBefore, NotOnOrAfter with clock skew)
+       */
+      const result = await saml.validatePostResponseAsync({
+        SAMLResponse: samlResponse,
+      });
+
+      if (!result.profile) {
+        throw new SamlValidationError(
+          SamlValidationErrorType.INVALID_SIGNATURE,
+          'SAML response validation failed: no profile returned'
+        );
+      }
+
+      profile = result.profile;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown SAML validation error';
+
+      /**
+       * Determine specific error type based on error message
+       */
+      if (message.includes('signature')) {
+        throw new SamlValidationError(
+          SamlValidationErrorType.INVALID_SIGNATURE,
+          `SAML signature validation failed: ${message}`
+        );
+      }
+
+      if (message.includes('expired') || message.includes('NotOnOrAfter') || message.includes('NotBefore')) {
+        throw new SamlValidationError(
+          SamlValidationErrorType.EXPIRED_ASSERTION,
+          `SAML assertion time validation failed: ${message}`
+        );
+      }
+
+      if (message.includes('audience') || message.includes('Audience')) {
+        throw new SamlValidationError(
+          SamlValidationErrorType.INVALID_AUDIENCE,
+          `SAML audience validation failed: ${message}`
+        );
+      }
+
+      /**
+       * Fallback for unknown error types
+       * Note: Error classification relies on message text which may change between library versions
+       */
+      throw new SamlValidationError(
+        SamlValidationErrorType.VALIDATION_FAILED,
+        `SAML validation failed: ${message}`
+      );
+    }
+
     /**
-     * @todo Implement using @node-saml/node-saml
-     *
-     * This method should:
-     * 1. Decode base64 SAML Response
-     * 2. Validate XML signature using x509Cert
-     * 3. Validate Audience (should match SSO_SP_ENTITY_ID)
-     * 4. Validate Recipient (should match acsUrl)
-     * 5. Validate InResponseTo (should match saved AuthnRequest ID)
-     * 6. Validate time conditions (NotBefore, NotOnOrAfter)
-     * 7. Extract NameID
-     * 8. Extract email using attributeMapping
-     * 9. Extract name using attributeMapping (if available)
-     * 10. Return parsed data
+     * Extract NameID (Profile type defines nameID as required string)
      */
-    throw new Error('Not implemented');
+    const nameId = profile.nameID;
+
+    if (!nameId) {
+      throw new SamlValidationError(
+        SamlValidationErrorType.INVALID_NAME_ID,
+        'SAML response does not contain NameID'
+      );
+    }
+
+    /**
+     * Extract InResponseTo and validate if expectedRequestId provided
+     * Profile uses index signature [attributeName: string]: unknown for additional properties
+     */
+    const inResponseTo = profile.inResponseTo as string | undefined;
+
+    if (expectedRequestId && inResponseTo !== expectedRequestId) {
+      throw new SamlValidationError(
+        SamlValidationErrorType.INVALID_IN_RESPONSE_TO,
+        `InResponseTo mismatch: expected ${expectedRequestId}, got ${inResponseTo}`,
+        { expected: expectedRequestId, received: inResponseTo }
+      );
+    }
+
+    /**
+     * Extract attributes from profile
+     * node-saml puts SAML attributes directly on the profile object via index signature
+     */
+    const attributes = profile as unknown as Record<string, string | string[]>;
+
+    /**
+     * Extract email using attributeMapping
+     */
+    const email = extractAttribute(attributes, samlConfig.attributeMapping.email);
+
+    if (!email) {
+      throw new SamlValidationError(
+        SamlValidationErrorType.MISSING_EMAIL,
+        `Email attribute not found in SAML response. Expected attribute: ${samlConfig.attributeMapping.email}`,
+        { attributeMapping: samlConfig.attributeMapping }
+      );
+    }
+
+    /**
+     * Extract name using attributeMapping (optional)
+     */
+    let name: string | undefined;
+
+    if (samlConfig.attributeMapping.name) {
+      name = extractAttribute(attributes, samlConfig.attributeMapping.name);
+    }
+
+    return {
+      nameId,
+      email,
+      name,
+      inResponseTo,
+    };
   }
 
+  /**
+   * Create node-saml SAML instance with given configuration
+   *
+   * @param acsUrl - Assertion Consumer Service URL
+   * @param samlConfig - SAML configuration from workspace
+   * @returns configured SAML instance
+   */
+   private createSamlInstance(acsUrl: string, samlConfig: SamlConfig): SAML {
+    const spEntityId = process.env.SSO_SP_ENTITY_ID;
+
+    if (!spEntityId) {
+      throw new Error('SSO_SP_ENTITY_ID environment variable is not set');
+    }
+
+    const options: NodeSamlConfig = {
+      callbackUrl: acsUrl,
+      entryPoint: samlConfig.ssoUrl,
+      issuer: spEntityId,
+      idpIssuer: samlConfig.idpEntityId,
+      idpCert: samlConfig.x509Cert,
+      wantAssertionsSigned: true,
+      wantAuthnResponseSigned: false,
+      /**
+       * Allow 2 minutes clock skew for time validation
+       */
+      acceptedClockSkewMs: 2 * 60 * 1000,
+    };
+
+    if (samlConfig.nameIdFormat) {
+      options.identifierFormat = samlConfig.nameIdFormat;
+    }
+
+    return new SAML(options);
+  }
 }
 

src/sso/saml/types.ts

@@ -14,6 +14,11 @@ export enum SamlValidationErrorType {
   EXPIRED_ASSERTION = 'EXPIRED_ASSERTION',
   INVALID_NAME_ID = 'INVALID_NAME_ID',
   MISSING_EMAIL = 'MISSING_EMAIL',
+  /**
+   * Generic validation error when specific type cannot be determined
+   * Used as fallback when library error messages don't match known patterns
+   */
+  VALIDATION_FAILED = 'VALIDATION_FAILED',
 }
 
 /**

src/sso/saml/utils.ts

@@ -23,61 +23,3 @@ export function extractAttribute(attributes: Record<string, string | string[]>,
   return undefined;
 }
 
-/**
- * Validate PEM certificate format
- *
- * @param cert - certificate string
- * @returns true if certificate appears to be valid PEM format
- */
-export function isValidPemCertificate(cert: string): boolean {
-  return cert.includes('-----BEGIN CERTIFICATE-----') && cert.includes('-----END CERTIFICATE-----');
-}
-
-/**
- * Validate Audience value
- *
- * @param audience - audience value from SAML Assertion
- * @returns true if audience matches SSO_SP_ENTITY_ID
- * @throws Error if SSO_SP_ENTITY_ID environment variable is not set
- */
-export function validateAudience(audience: string): boolean {
-  const spEntityId = process.env.SSO_SP_ENTITY_ID;
-
-  if (!spEntityId) {
-    throw new Error('SSO_SP_ENTITY_ID environment variable is not set');
-  }
-
-  return audience === spEntityId;
-}
-
-/**
- * Validate Recipient value
- *
- * @param recipient - recipient URL from SAML Assertion
- * @param expectedAcsUrl - expected ACS URL
- * @returns true if recipient matches expected ACS URL
- */
-export function validateRecipient(recipient: string, expectedAcsUrl: string): boolean {
-  return recipient === expectedAcsUrl;
-}
-
-/**
- * Validate time conditions (NotBefore and NotOnOrAfter)
- *
- * @param notBefore - NotBefore timestamp
- * @param notOnOrAfter - NotOnOrAfter timestamp
- * @param clockSkew - allowed clock skew in milliseconds (default: 2 minutes)
- * @returns true if assertion is valid at current time
- */
-export function validateTimeConditions(
-  notBefore: Date,
-  notOnOrAfter: Date,
-  clockSkew: number = 2 * 60 * 1000
-): boolean {
-  const now = Date.now();
-  const notBeforeTime = notBefore.getTime() - clockSkew;
-  const notOnOrAfterTime = notOnOrAfter.getTime() + clockSkew;
-
-  return now >= notBeforeTime && now < notOnOrAfterTime;
-}
-