@wildo-ai/saas-backend-lib 1.0.1

package/src/security/authentications/services/auth-methods/saml-authentication.backend.service.ts

@@ -0,0 +1,1727 @@
+/**
+ * SAML Authentication Service — SSO + Single Logout
+ *
+ * Orchestrates the full SAML 2.0 authentication and logout flows:
+ * - `initiateLogin()` — generates AuthnRequest, creates state token, returns IdP redirect URL
+ * - `handleACS()` — processes SAML Response, validates assertion, provisions user, issues tokens
+ * - `handleIdPInitiatedSLO()` — processes IdP-initiated LogoutRequest (GET + POST)
+ * - `initiateSPLogout()` — builds LogoutRequest for SP-initiated SLO
+ * - `handleSLOResponse()` — processes IdP's LogoutResponse to SP-initiated SLO
+ *
+ * Parallels `OAuth2AuthenticationBackendService` for the OIDC flow.
+ * SAML is enterprise-only.
+ *
+ * Key design decisions:
+ * - D2: samlify SP/IdP objects created per-request from connection config (not cached)
+ * - D3: Request correlation via ConsumableToken with SAML_AUTH_STATE type
+ * - D8: wantMessageSigned hardcoded to true
+ * - D14: Hybrid SP-initiated + IdP-initiated connection resolution
+ * - D15: providerUserId = `${idpEntityId}|${nameId}`
+ * - TRAP 12: Uses `issueTokensForUser(entityId, false)` for JWT issuance
+ * - Token delivery via AUTH_CODE_EXCHANGE consumable token (never in URL query params)
+ * - SLO uses dual Redis mappings: forward (userId→sessionIndex) + reverse (sessionIndex→userId)
+ */
+
+import 'reflect-metadata';
+import { createRequire } from 'module';
+import { injectable, inject, optional } from 'inversify';
+import { createHash } from 'crypto';
+
+const require = createRequire(import.meta.url);
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import type { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';
+import { AuthUserLookupBackendService } from '~wildo-backend-lib/security/authentications/services/utils/auth-user-lookup.backend.service';
+import { AuthExecutionContextFactoryBackendService } from '~wildo-backend-lib/security/authentications/services/auth-execution-context-factory.backend.service';
+import { ConsumableTokenBackendService } from '~wildo-backend-lib/security/consumable-tokens/services/consumable-token.backend.service';
+import { SAMLAssertionValidatorBackendService } from './saml-assertion-validator.backend.service';
+import { SAMLMetadataBackendService } from './saml-metadata.backend.service';
+import { DomainToOrgLookupBackendService } from '~wildo-backend-lib/security/authentications/services/admin-config/domain-to-org-lookup.backend.service';
+import { EnterpriseUserProvisioningBackendService } from '~wildo-backend-lib/security/authentications/services/admin-config/enterprise-user-provisioning.backend.service';
+import { AuthControllerUtils } from '~wildo-backend-lib/security/authentications/services/utils/auth-controller.utils';
+import { AuditLogsBackendService } from '~wildo-backend-lib/compliance/audit-trails/services/audit-logs.backend.service';
+import { AuthTokenIssuerBackendService } from '~wildo-backend-lib/security/authentications/services/auth-token-issuer.backend.service';
+import { RedisService } from '~wildo-backend-lib/databases/services/redis.service';
+import type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import type { SAMLResolvedConnection, SAMLStateMetadata, SAMLAssertionData } from '~wildo-backend-lib/security/authentications/models/saml-authentication.backend.schemas';
+import type { NormalizedUserProfile } from '~wildo-backend-lib/security/authentications/models/sso-connection.backend.schemas';
+import type { SamlifyParsedResponse } from './saml-assertion-validator.backend.service';
+import {
+  checkJavaAvailability,
+  isTestEnvironment,
+} from '~wildo-backend-lib/security/authentications/services/utils/saml-java-availability';
+import { AuthSource, SsoProtocol } from '~wildo-backend-lib/security/authentications/models/auth-constants.backend';
+import {
+  CoreConsumableTokenTypes,
+  ConsumableToken_ConsumptionMode,
+  CoreResourceType,
+  CoreAuditableEventType,
+  ResourceOperationRiskLevel,
+  ErrorType,
+  ErrorCustomMessageReference,
+  isWildoBackendError,
+  SsoConnectionType,
+  AuthScopeType,
+  UserStatus,
+} from '@wildo-ai/saas-models';
+import type { SsoConnectionBase, User, UserIdentityLink } from '@wildo-ai/saas-models';
+import { DurationUnit } from '@wildo-ai/zod-decorators';
+
+/** SLO parse result from samlify's sp.parseLogoutRequest — extract shape varies by binding */
+interface SAMLSlOParseResult {
+  extract?: {
+    logoutRequest?: { sessionIndex?: string; nameID?: string; id?: string };
+    sessionIndex?: string;
+    nameID?: string;
+    request?: { id?: string };
+  };
+  samlContent: string;
+}
+
+/** SsoConnection with scope fields for org/app polymorphic resolution */
+type SsoConnectionWithScope = SsoConnectionBase & { organizationId?: string; applicationId?: string };
+
+// ─────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────
+
+const SAML_BINDINGS = {
+  REDIRECT: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
+  POST: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
+} as const;
+
+const MAX_RESPONSE_SIZE = 2 * 1024 * 1024; // 2MB (SC-20, E18)
+const TRANSIENT_NAMEID_FORMAT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient';
+const SAML_SESSION_TTL = 86400; // 24h — matches refresh token lifetime
+
+/**
+ * Common alternative attribute URIs for fallback resolution (E17).
+ * Keys are canonical profile fields; values are ordered fallback lists.
+ */
+const COMMON_ATTRIBUTE_ALTERNATIVES: Record<string, string[]> = {
+  email: [
+    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress',
+    'http://schemas.xmlsoap.org/claims/EmailAddress',
+    'urn:oid:0.9.2342.19200300.100.1.3',
+    'mail', 'email', 'emailAddress',
+  ],
+  firstName: [
+    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname',
+    'urn:oid:2.5.4.42',
+    'givenName', 'given_name', 'firstName',
+  ],
+  lastName: [
+    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname',
+    'urn:oid:2.5.4.4',
+    'sn', 'surname', 'family_name', 'lastName',
+  ],
+  roles: [
+    'http://schemas.microsoft.com/ws/2008/06/identity/claims/role',
+    'urn:oid:1.3.6.1.4.1.5923.1.1.1.7',
+    'roles', 'Role', 'memberOf',
+  ],
+  groups: [
+    'http://schemas.microsoft.com/ws/2008/06/identity/claims/groups',
+    'groups', 'Group',
+  ],
+  department: [
+    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/department',
+    'urn:oid:2.5.4.11',
+    'department', 'ou',
+  ],
+  employeeId: [
+    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeid',
+    'urn:oid:2.16.840.1.113730.3.1.3',
+    'employeeId', 'employeeNumber',
+  ],
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Internal types
+// ─────────────────────────────────────────────────────────────────
+
+interface ConnectionResolutionResult {
+  resolvedConnection: SAMLResolvedConnection;
+  stateMetadata?: SAMLStateMetadata;
+  scopeType: string;
+  scopeId: string;
+}
+
+/** Test-only: when bound, used instead of samlify parseLoginResponse (avoids XSD/Java). Production never binds. */
+export interface SAMLResponseParserOverride {
+  parse(
+    connection: SAMLResolvedConnection,
+    samlResponse: string,
+  ): Promise<SamlifyParsedResponse & { validatingCertIndex: number }>;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Service
+// ─────────────────────────────────────────────────────────────────
+
+@injectable()
+export class SAMLAuthenticationBackendService {
+  private readonly logDebug: (message: string, context?: Record<string, unknown>) => void;
+  private samlifyInitialized = false;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly appConfigService: AppConfigurationService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService) private readonly servicesRegistryHandler: ServicesRegistryHandlerBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthUserLookupService) private readonly userLookup: AuthUserLookupBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthExecutionContextFactory) private readonly authEcFactory: AuthExecutionContextFactoryBackendService,
+    @inject(SAAS_SERVICE_TYPES.ConsumableTokenService) private readonly consumableTokenService: ConsumableTokenBackendService,
+    @inject(SAAS_SERVICE_TYPES.SAMLAssertionValidatorService) private readonly assertionValidator: SAMLAssertionValidatorBackendService,
+    @inject(SAAS_SERVICE_TYPES.SAMLMetadataService) private readonly metadataService: SAMLMetadataBackendService,
+    @inject(SAAS_SERVICE_TYPES.DomainToOrgLookupService) private readonly domainToOrgLookup: DomainToOrgLookupBackendService,
+    @inject(SAAS_SERVICE_TYPES.EnterpriseUserProvisioningService) private readonly enterpriseProvisioning: EnterpriseUserProvisioningBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuditLogsService) private readonly auditLogsService: AuditLogsBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthTokenIssuer) private readonly tokenIssuer: AuthTokenIssuerBackendService,
+    @inject(SAAS_SERVICE_TYPES.RedisService) private readonly redisService: RedisService,
+    @inject(SAAS_SERVICE_TYPES.SAMLResponseParserOverride) @optional() private readonly samlResponseParserOverride?: SAMLResponseParserOverride,
+  ) {
+    this.logDebug = this.logger.debugByType('SAMLAuthentication');
+    this.logger.setDebugTypeLogging('SAMLAuthentication', false);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // 1. Login Initiation (SP-Initiated SSO)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Generate a SAML AuthnRequest and return the IdP redirect URL.
+   *
+   * Flow:
+   * 1. Load and validate the SAML connection
+   * 2. Validate returnUrl against open redirect (SC-26, E21)
+   * 3. Create samlify SP + IdP objects (D2 — per-request)
+   * 4. Generate AuthnRequest
+   * 5. Create ConsumableToken with SAMLStateMetadata (D3)
+   * 6. Append RelayState to redirect URL
+   * 7. Emit audit event
+   */
+  public async initiateLogin(
+    ec: ExecutionContext<any>,
+    connectionId: string,
+    returnUrl: string,
+  ): Promise<{ redirectUrl: string }> {
+    const appDomain = this._getAppDomain();
+
+    this._validateReturnUrl(returnUrl, appDomain);
+
+    const { connection, scopeType, scopeId } = await this._loadConnectionFromAnyScope(ec, connectionId);
+
+    if (connection.protocol !== SsoProtocol.SAML || !connection.saml) {
+      throw this._buildAuthError(
+        ErrorCustomMessageReference.SAML_ASSERTION_INVALID,
+        'Connection is not configured for SAML protocol',
+      );
+    }
+
+    if (connection.saml.signRequests && !process.env.SAML_SP_PRIVATE_KEY) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.SAML_ASSERTION_INVALID,
+        context: { message: 'SAML_SP_PRIVATE_KEY environment variable required when signRequests is enabled' },
+      });
+    }
+
+    const spEntityId = `https://${appDomain}/saml/sp/${scopeType}/${scopeId}`;
+    const acsUrl = `https://${appDomain}/auth/saml/acs`;
+
+    const saml = this._getSamlifyModule();
+
+    const sp = saml.ServiceProvider({
+      entityID: spEntityId,
+      authnRequestsSigned: connection.saml.signRequests,
+      wantAssertionsSigned: connection.saml.wantAssertionsSigned,
+      wantMessageSigned: true,
+      signingCert: process.env.SAML_SP_CERTIFICATE,
+      privateKey: connection.saml.signRequests ? process.env.SAML_SP_PRIVATE_KEY : undefined,
+      encPrivateKey: process.env.SAML_SP_PRIVATE_KEY,
+      nameIDFormat: [connection.saml.nameIdFormat],
+      assertionConsumerService: [{ Binding: SAML_BINDINGS.POST, Location: acsUrl }],
+    });
+
+    const idp = saml.IdentityProvider({
+      entityID: connection.saml.entityId,
+      singleSignOnService: [{ Binding: SAML_BINDINGS.REDIRECT, Location: connection.saml.ssoUrl }],
+      signingCert: connection.saml.x509Certificates[0],
+      nameIDFormat: [connection.saml.nameIdFormat],
+    });
+
+    const loginRequest = sp.createLoginRequest(idp, 'redirect');
+    const authnRequestId: string = loginRequest.id;
+    const redirectContext: string = loginRequest.context;
+
+    const stateToken = await this.consumableTokenService.createToken({
+      tokenType: CoreConsumableTokenTypes.SAML_AUTH_STATE,
+      consumptionMode: ConsumableToken_ConsumptionMode.EPHEMERAL_STATE,
+      expiresIn: { value: 10, unit: DurationUnit.MINUTES },
+      metadata: {
+        requestId: authnRequestId,
+        connectionId,
+        scopeType,
+        scopeId,
+        returnUrl,
+        initiatedAt: Date.now(),
+      } as unknown as Record<string, any>,
+    });
+
+    const separator = redirectContext.includes('?') ? '&' : '?';
+    const redirectUrl = `${redirectContext}${separator}RelayState=${encodeURIComponent(stateToken.token)}`;
+
+    this.logDebug('SAML login initiated', {
+      connectionId,
+      idpEntityId: connection.saml.entityId,
+      requestId: authnRequestId,
+    });
+
+    this.auditLogsService.logSAMLEvent(
+      CoreAuditableEventType.SAML_LOGIN_INITIATED,
+      ResourceOperationRiskLevel.LOW,
+      {
+        connectionId,
+        idpEntityId: connection.saml.entityId,
+        requestId: authnRequestId,
+        organizationId: scopeId,
+        authSource: AuthSource.SAML,
+      },
+    ).catch(() => { /* fire-and-forget */ });
+
+    return { redirectUrl };
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // 2. ACS Handler (Assertion Consumer Service)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Process a SAML Response at the Assertion Consumer Service endpoint.
+   *
+   * Handles both SP-initiated (RelayState present) and IdP-initiated
+   * (RelayState absent) flows per D14.
+   *
+   * Flow:
+   * 1.  Response size check (SC-20, E18)
+   * 2.  Resolve connection (SP-initiated or IdP-initiated)
+   * 3.  Parse SAML Response with multi-cert rotation (SC-14)
+   * 4.  Validate assertion via SAMLAssertionValidatorService
+   * 5.  Extract user profile via attribute mapping (E17)
+   * 6.  Unicode normalize email domain (SC-23, E27)
+   * 7.  Domain verification check (E11)
+   * 8.  Derive providerUserId (D15, E29)
+   * 9.  Provision/link user via EnterpriseUserProvisioningService (E12)
+   * 10. Store SessionIndex for SLO (SC-33, E13)
+   * 11. Issue JWT tokens via AUTH_CODE_EXCHANGE pattern
+   * 12. Emit audit event
+   * 13. Return redirect URL
+   */
+  public async handleACS(
+    ec: ExecutionContext<any>,
+    samlResponse: string,
+    relayState?: string,
+    clientContext?: { ipAddress: string; userAgent: string },
+  ): Promise<{ redirectUrl: string; userId: string }> {
+    if (samlResponse.length > MAX_RESPONSE_SIZE) {
+      throw this._buildAuthError(
+        ErrorCustomMessageReference.SAML_ASSERTION_INVALID,
+        'SAML response exceeds maximum allowed size of 2MB',
+      );
+    }
+
+    const internalEc = await this._getInternalExecutionContext();
+    const appDomain = this._getAppDomain();
+
+    // ── Step 2: Resolve connection ──
+    const resolution = await this._resolveConnection(internalEc, samlResponse, relayState, appDomain);
+    const { resolvedConnection, stateMetadata, scopeType, scopeId } = resolution;
+
+    try {
+      // ── Step 3: Parse SAML Response (override for tests; production uses samlify) ──
+      const parseResultWithCertInfo = this.samlResponseParserOverride
+        ? await this.samlResponseParserOverride.parse(resolvedConnection, samlResponse)
+        : await this._parseSAMLResponseWithMultiCert(resolvedConnection, samlResponse);
+      const { validatingCertIndex, ...parseResult } = parseResultWithCertInfo;
+
+      // ── Step 4: Validate assertion ──
+      const assertionData = await this.assertionValidator.validateAssertion(
+        parseResult,
+        resolvedConnection,
+        resolvedConnection.spEntityId,
+        resolvedConnection.acsUrl,
+        stateMetadata,
+      );
+
+      // ── Step 5: Extract user profile via attribute mapping (E17) ──
+      const userProfile = this._extractUserProfileFromAssertion(assertionData, resolvedConnection);
+
+      // ── Step 6: Unicode normalization on email domain (SC-23, E27) ──
+      const emailParts = userProfile.email.split('@');
+      if (emailParts.length === 2) {
+        userProfile.email = `${emailParts[0]}@${emailParts[1].normalize('NFKC')}`;
+      }
+
+      // ── Step 7: Domain verification check (E11) ──
+      const emailDomain = userProfile.email.split('@')[1];
+      if (emailDomain) {
+        const domainCheck = await this.domainToOrgLookup.findOrgByDomain(internalEc, emailDomain);
+        if (!domainCheck) {
+          throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+            customMessageReference: ErrorCustomMessageReference.SAML_DOMAIN_NOT_VERIFIED,
+            context: { message: 'Email domain is not verified for SSO', domain: emailDomain },
+          });
+        }
+      }
+
+      // ── Step 8: Derive providerUserId (D15, E12, E29) ──
+      let providerUserId = `${resolvedConnection.idpEntityId}|${assertionData.nameId}`;
+
+      if (assertionData.nameIdFormat === TRANSIENT_NAMEID_FORMAT) {
+        const persistentAttrUri =
+          resolvedConnection.attributeMapping['persistentId'] ||
+          resolvedConnection.attributeMapping['providerUserId'];
+        if (persistentAttrUri) {
+          const persistentValue = this._resolveAttributeValue(assertionData.attributes, persistentAttrUri);
+          if (persistentValue) {
+            providerUserId = `${resolvedConnection.idpEntityId}|${persistentValue}`;
+          }
+        }
+      }
+      userProfile.providerUserId = providerUserId;
+
+      // ── Step 9: Provision/link user (E12) ──
+      if (!resolvedConnection.organization) {
+        throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.SAML_ORGANIZATION_REQUIRED,
+          context: { message: 'SAML SSO is only available for enterprise connections' },
+        });
+      }
+
+      const org = resolvedConnection.organization;
+
+      // W7.2: Block cross-org SSO when disabled
+      if (this.appConfigService.config.auth.crossOrgSSOAccess === false) {
+        const existingUser = await this.userLookup.findAnyUserByEmail(ec, userProfile.email);
+        if (existingUser) {
+          const enterpriseLinks: UserIdentityLink[] = await this.servicesRegistryHandler.list<UserIdentityLink>(
+            CoreResourceType.USER_IDENTITY_LINKS, ec,
+            { userId: existingUser._id, connectionType: 'enterprise' },
+            undefined, { paginated: false },
+          ) as UserIdentityLink[] ?? [];
+          const hasCrossOrgLink = enterpriseLinks.some(
+            (link) => link.organizationId && link.organizationId !== org.organizationId,
+          );
+          if (hasCrossOrgLink) {
+            this.logDebug('Cross-org SSO blocked (SAML)', { userId: existingUser._id, targetOrg: org.organizationId });
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+              customMessageReference: ErrorCustomMessageReference.CROSS_ORG_SSO_BLOCKED,
+              context: { message: 'Cross-organization SSO access is not allowed.' },
+            });
+          }
+        }
+      }
+
+      const provisionResult = await this.enterpriseProvisioning.createOrgUser(
+        userProfile,
+        resolvedConnection,
+        {
+          organizationId: org.organizationId,
+          autoCreateUsers: org.autoCreateUsers,
+          autoVerifyEmail: org.autoVerifyEmail,
+          defaultRole: org.defaultRole,
+          roleMapping: org.roleMapping,
+          groupMapping: org.groupMapping,
+          allowedDomains: org.allowedDomains || [],
+        },
+      );
+
+      const userId = provisionResult.user._id;
+
+      // ── Step 10: Store SessionIndex for SLO (SC-33, E13) ──
+      if (assertionData.sessionIndex) {
+        try {
+          const sessionKey = `saml:session:${userId}:${org.connectionId}`;
+          await this.redisService.set(
+            sessionKey,
+            { sessionIndex: assertionData.sessionIndex, nameId: assertionData.nameId },
+            { ttl: SAML_SESSION_TTL },
+          );
+
+          const reverseKey = this._sloReverseKey(org.connectionId, assertionData.sessionIndex);
+          await this.redisService.set(reverseKey, { userId, connectionId: org.connectionId }, { ttl: SAML_SESSION_TTL });
+        } catch {
+          this.logger.warn('Failed to store SAML session index for SLO', {
+            userId,
+            connectionId: org.connectionId,
+          });
+        }
+      }
+
+      // ── Step 10b: Verify user status before token issuance (W2-SEC-3) ──
+      const user = provisionResult.user;
+      if (!user || user.status !== UserStatus.ACTIVE) {
+        throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_ACCOUNT_LOCKED,
+          context: { userStatus: user?.status ?? 'UNKNOWN', source: 'saml_acs' },
+        });
+      }
+
+      // ── Step 11: Issue JWT tokens (TRAP 12) + AUTH_CODE_EXCHANGE ──
+      const tokens = await this.tokenIssuer.issueTokensForUser(userId, undefined, {
+        lastAuthenticatedAt: Math.floor(Date.now() / 1000),
+      });
+
+      const exchangeToken = await this.consumableTokenService.createToken({
+        tokenType: CoreConsumableTokenTypes.AUTH_CODE_EXCHANGE,
+        consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
+        expiresIn: { value: 5, unit: DurationUnit.MINUTES },
+        userId,
+        resourceIdentifier: CoreResourceType.USERS,
+        metadata: {
+          accessToken: tokens.accessToken,
+          refreshToken: tokens.refreshToken,
+          expiresIn: tokens.expiresIn,
+          providerRef: resolvedConnection.providerRef,
+          isNewUser: provisionResult.isNew,
+          },
+      });
+
+      // ── Step 12: Emit audit events — success ──
+      try {
+        await this.auditLogsService.logUserSSOLogin({
+          userId,
+          email: userProfile.email,
+          providerRef: resolvedConnection.providerRef,
+          connectionType: SsoConnectionType.ENTERPRISE,
+          authSource: AuthSource.SAML,
+          organizationId: org.organizationId,
+          ipAddress: clientContext?.ipAddress || 'unknown',
+          userAgent: clientContext?.userAgent || 'unknown',
+          sessionId: `saml:${resolvedConnection.providerRef}:${userId}`,
+        });
+      } catch { /* audit failure must not block authentication */ }
+
+      this.auditLogsService.logSAMLEvent(
+        CoreAuditableEventType.SAML_LOGIN_SUCCESS,
+        ResourceOperationRiskLevel.LOW,
+        {
+          connectionId: org.connectionId,
+          idpEntityId: resolvedConnection.idpEntityId,
+          assertionId: assertionData.assertionId,
+          nameId: assertionData.nameId,
+          sessionIndex: assertionData.sessionIndex,
+          userId,
+          organizationId: org.organizationId,
+          validatingCertIndex,
+          initiatedBy: stateMetadata ? 'sp' : 'idp',
+          authSource: AuthSource.SAML,
+        },
+      ).catch(() => { /* fire-and-forget */ });
+
+      this.logDebug('SAML ACS processed successfully', {
+        userId,
+        providerRef: resolvedConnection.providerRef,
+        isNew: provisionResult.isNew,
+        assertionId: assertionData.assertionId,
+      });
+
+      // ── Step 13: Return redirect URL ──
+      // Resolve the correct frontend URL from the user's type via the
+      // frontendServices.usersManagement reverse lookup.
+      const userType = user.userTypes?.[0];
+      const resolvedFrontendServiceName = userType
+        ? this.appConfigService.resolveFrontendServiceNameFromUserType(userType)
+        : this.appConfigService.resolveDefaultFrontendServiceName();
+
+      if (resolvedFrontendServiceName && userType) {
+        const userManagement = this.appConfigService.getFrontendServiceUserManagementEntry(resolvedFrontendServiceName, userType);
+        if (!userManagement?.auth) {
+          throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+            customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
+            context: {
+              message: `Authentication is disabled for frontend service "${resolvedFrontendServiceName}" and user type "${userType}"`,
+              frontendServiceName: resolvedFrontendServiceName,
+              activeUserType: userType,
+            },
+          });
+        }
+      }
+
+      const config = this.appConfigService.config;
+      const frontendUrl = resolvedFrontendServiceName
+        ? AuthControllerUtils.lookupFrontendPublicUrl(config, resolvedFrontendServiceName)
+        : null;
+      if (!frontendUrl) {
+        throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+          context: {
+            message: 'Cannot resolve a frontend publicUrl for SAML callback redirection.',
+            frontendServiceName: resolvedFrontendServiceName,
+            appDomain,
+          },
+        });
+      }
+      const searchParams = new URLSearchParams({
+        code: exchangeToken.token,
+      });
+      if (resolution.stateMetadata?.returnUrl) {
+        searchParams.set('redirect', resolution.stateMetadata.returnUrl);
+      }
+      const redirectUrl = `${frontendUrl}/auth/callback?${searchParams.toString()}`;
+
+      return { redirectUrl, userId };
+
+    } catch (error) {
+      if (isWildoBackendError(error)) {
+        this._emitFailureAudit(resolvedConnection, String(error.customMessageReference ?? 'unknown'), clientContext);
+        throw error;
+      }
+
+      this.logger.error('SAML ACS handler failed with unexpected error', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      this._emitFailureAudit(resolvedConnection, error instanceof Error ? error.message : 'unknown', clientContext);
+
+      throw this._buildAuthError(
+        ErrorCustomMessageReference.SAML_ASSERTION_INVALID,
+        'SAML authentication failed',
+      );
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // 3. Single Logout — IdP-Initiated (SC-34, SC-35, SC-37)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Handle an IdP-initiated SAML SLO request.
+   *
+   * Supports both HTTP-Redirect (GET) and HTTP-POST bindings.
+   * The IdP sends a LogoutRequest telling us to terminate a user's session.
+   *
+   * Flow:
+   * 1. Parse & validate the LogoutRequest via samlify (SC-34)
+   * 2. Extract Issuer → resolve connection
+   * 3. Extract SessionIndex → find active session via reverse mapping
+   * 4. Terminate local session (delete Redis mappings) (SC-37)
+   * 5. Build and return LogoutResponse
+   * 6. Graceful no-op if no active session (SC-35, E15)
+   */
+  public async handleIdPInitiatedSLO(
+    ec: ExecutionContext<any>,
+    binding: 'redirect' | 'post',
+    samlRequest: string,
+    relayState?: string,
+  ): Promise<{ logoutResponseUrl: string; binding: 'redirect' | 'post' }> {
+    const internalEc = await this._getInternalExecutionContext();
+    const appDomain = this._getAppDomain();
+
+    const issuer = this._extractIssuerFromLogoutRequest(samlRequest, binding);
+    if (!issuer) {
+      throw this._buildAuthError(
+        ErrorCustomMessageReference.SAML_UNKNOWN_IDP,
+        'Cannot extract Issuer from SAML LogoutRequest',
+      );
+    }
+
+    const matches = await this._findConnectionsByEntityId(internalEc, issuer);
+    if (matches.length === 0) {
+      throw this._buildAuthError(
+        ErrorCustomMessageReference.SAML_UNKNOWN_IDP,
+        'No SSO connection found for IdP entity ID in SLO request',
+      );
+    }
+
+    const { connection, scopeType, scopeId } = matches[0];
+    const resolvedConnection = this._buildResolvedConnection(connection, scopeType, scopeId, appDomain);
+
+    let parseResult: SAMLSlOParseResult;
+    try {
+      parseResult = await this._parseSLORequestWithMultiCert(resolvedConnection, binding, samlRequest);
+    } catch (error) {
+      this.logger.warn('SLO request signature verification failed', {
+        idpEntityId: resolvedConnection.idpEntityId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw this._buildAuthError(
+        ErrorCustomMessageReference.SAML_SIGNATURE_INVALID,
+        'SAML LogoutRequest signature verification failed',
+      );
+    }
+
+    const extract = parseResult.extract;
+    const sessionIndex: string | undefined =
+      extract?.logoutRequest?.sessionIndex ?? extract?.sessionIndex;
+    const nameId: string | undefined =
+      extract?.logoutRequest?.nameID ?? extract?.nameID;
+    const requestId: string | undefined =
+      extract?.logoutRequest?.id ?? extract?.request?.id;
+
+    let terminatedUserId: string | undefined;
+    let sloResult: 'success' | 'no-session' = 'no-session';
+
+    if (sessionIndex) {
+      const sessionData = await this._findSessionByIndex(resolvedConnection.organization?.connectionId || connection._id, sessionIndex);
+
+      if (sessionData) {
+        terminatedUserId = sessionData.userId;
+        await this._terminateSAMLSession(sessionData.userId, sessionData.connectionId, sessionIndex);
+        sloResult = 'success';
+      }
+    }
+
+    this.logDebug('IdP-initiated SLO processed', {
+      idpEntityId: resolvedConnection.idpEntityId,
+      sessionIndex,
+      nameId,
+      result: sloResult,
+      userId: terminatedUserId,
+    });
+
+    this._emitSLOAudit(resolvedConnection, sessionIndex, 'idp-initiated', sloResult);
+
+    const responseContext = this._buildLogoutResponse(
+      resolvedConnection,
+      requestId || '',
+      binding,
+      relayState,
+    );
+
+    return { logoutResponseUrl: responseContext.url, binding };
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // 4. Single Logout — SP-Initiated (SC-36, SC-37)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Initiate SP-initiated SAML SLO. Terminates the local session and
+   * redirects the user to the IdP's SLO URL with a LogoutRequest.
+   *
+   * The IdP will process the LogoutRequest and send a LogoutResponse
+   * back to our SLO endpoint. Local cleanup happens regardless (SC-37).
+   */
+  public async initiateSPLogout(
+    ec: ExecutionContext<any>,
+    userId: string,
+    connectionId: string,
+  ): Promise<{ redirectUrl: string } | null> {
+    const internalEc = await this._getInternalExecutionContext();
+    const appDomain = this._getAppDomain();
+
+    let connection: SsoConnectionBase;
+    let scopeType: string;
+    let scopeId: string;
+    try {
+      const loaded = await this._loadConnectionFromAnyScope(internalEc, connectionId);
+      connection = loaded.connection;
+      scopeType = loaded.scopeType;
+      scopeId = loaded.scopeId;
+    } catch {
+      this.logger.warn('SP-initiated SLO: connection not found', { connectionId });
+      return null;
+    }
+
+    if (connection.protocol !== SsoProtocol.SAML || !connection.saml) {
+      return null;
+    }
+
+    const resolvedConnection = this._buildResolvedConnection(connection, scopeType, scopeId, appDomain);
+
+    if (!resolvedConnection.sloUrl) {
+      this.logDebug('SP-initiated SLO: IdP does not support SLO (no sloUrl)', {
+        connectionId,
+        idpEntityId: resolvedConnection.idpEntityId,
+      });
+      await this._terminateSAMLSessionByUser(userId, connectionId);
+      return null;
+    }
+
+    const forwardKey = `saml:session:${userId}:${connectionId}`;
+    const forwardData = await this.redisService.get<{ sessionIndex: string; nameId: string }>(forwardKey);
+    const sessionIndex = forwardData?.sessionIndex;
+    const nameId = forwardData?.nameId;
+
+    await this._terminateSAMLSessionByUser(userId, connectionId);
+
+    const saml = this._getSamlifyModule();
+    const sloUrl = `https://${appDomain}/auth/saml/slo`;
+
+    const sp = saml.ServiceProvider({
+      entityID: resolvedConnection.spEntityId,
+      authnRequestsSigned: resolvedConnection.signRequests,
+      wantAssertionsSigned: resolvedConnection.wantAssertionsSigned,
+      wantMessageSigned: true,
+      signingCert: process.env.SAML_SP_CERTIFICATE,
+      privateKey: process.env.SAML_SP_PRIVATE_KEY,
+      nameIDFormat: [resolvedConnection.nameIdFormat],
+      assertionConsumerService: [{ Binding: SAML_BINDINGS.POST, Location: resolvedConnection.acsUrl }],
+      singleLogoutService: [
+        { Binding: SAML_BINDINGS.REDIRECT, Location: sloUrl },
+        { Binding: SAML_BINDINGS.POST, Location: sloUrl },
+      ],
+    });
+
+    const idp = saml.IdentityProvider({
+      entityID: resolvedConnection.idpEntityId,
+      singleSignOnService: [{ Binding: SAML_BINDINGS.REDIRECT, Location: resolvedConnection.ssoUrl }],
+      singleLogoutService: [{ Binding: SAML_BINDINGS.REDIRECT, Location: resolvedConnection.sloUrl }],
+      signingCert: resolvedConnection.x509Certificates[0],
+      nameIDFormat: [resolvedConnection.nameIdFormat],
+    });
+
+    const logoutRequest = sp.createLogoutRequest(
+      idp,
+      'redirect',
+      { logoutNameID: nameId || userId, sessionIndex: sessionIndex || undefined },
+    ) as { context: string; id: string };
+
+    this.logDebug('SP-initiated SLO: LogoutRequest created', {
+      connectionId,
+      userId,
+      requestId: logoutRequest.id,
+    });
+
+    this._emitSLOAudit(resolvedConnection, sessionIndex || undefined, 'sp-initiated', 'success');
+
+    return { redirectUrl: logoutRequest.context };
+  }
+
+  /**
+   * Handle the IdP's LogoutResponse to our SP-initiated SLO request.
+   * At this point, local cleanup already happened in `initiateSPLogout()`.
+   * We just validate the response and redirect the user to the frontend.
+   */
+  public async handleSLOResponse(
+    ec: ExecutionContext<any>,
+    binding: 'redirect' | 'post',
+    samlResponse: string,
+  ): Promise<void> {
+    this.logDebug('SP-initiated SLO: LogoutResponse received from IdP', { binding });
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // SLO Helpers
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Parse a SAML LogoutRequest using samlify, trying each configured IdP
+   * certificate in sequence (mirrors ACS multi-cert rotation — SC-14).
+   */
+  private async _parseSLORequestWithMultiCert(
+    connection: SAMLResolvedConnection,
+    binding: 'redirect' | 'post',
+    samlRequest: string,
+  ): Promise<SAMLSlOParseResult> {
+    const saml = this._getSamlifyModule();
+    const appDomain = this._getAppDomain();
+    const sloUrl = `https://${appDomain}/auth/saml/slo`;
+    let lastError: unknown;
+
+    for (const cert of connection.x509Certificates) {
+      try {
+        const sp = saml.ServiceProvider({
+          entityID: connection.spEntityId,
+          authnRequestsSigned: connection.signRequests,
+          wantAssertionsSigned: connection.wantAssertionsSigned,
+          wantMessageSigned: true,
+          signingCert: process.env.SAML_SP_CERTIFICATE,
+          privateKey: process.env.SAML_SP_PRIVATE_KEY,
+          nameIDFormat: [connection.nameIdFormat],
+          assertionConsumerService: [{ Binding: SAML_BINDINGS.POST, Location: connection.acsUrl }],
+          singleLogoutService: [
+            { Binding: SAML_BINDINGS.REDIRECT, Location: sloUrl },
+            { Binding: SAML_BINDINGS.POST, Location: sloUrl },
+          ],
+        });
+
+        const idp = saml.IdentityProvider({
+          entityID: connection.idpEntityId,
+          singleSignOnService: [{ Binding: SAML_BINDINGS.REDIRECT, Location: connection.ssoUrl }],
+          singleLogoutService: connection.sloUrl
+            ? [{ Binding: SAML_BINDINGS.REDIRECT, Location: connection.sloUrl },
+               { Binding: SAML_BINDINGS.POST, Location: connection.sloUrl }]
+            : [],
+          signingCert: cert,
+          nameIDFormat: [connection.nameIdFormat],
+        });
+
+        const requestObj = binding === 'redirect'
+          ? { query: { SAMLRequest: samlRequest } }
+          : { body: { SAMLRequest: samlRequest } };
+
+        const result = await sp.parseLogoutRequest(idp, binding, requestObj);
+        return result as SAMLSlOParseResult;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+
+    throw lastError || new Error('SLO request parsing failed');
+  }
+
+  /**
+   * Find the userId for a given SessionIndex via the reverse mapping.
+   */
+  private async _findSessionByIndex(
+    connectionId: string,
+    sessionIndex: string,
+  ): Promise<{ userId: string; connectionId: string } | null> {
+    try {
+      const reverseKey = this._sloReverseKey(connectionId, sessionIndex);
+      return await this.redisService.get<{ userId: string; connectionId: string }>(reverseKey);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Clean up SAML session state in Redis: forward + reverse mappings.
+   */
+  private async _terminateSAMLSession(
+    userId: string,
+    connectionId: string,
+    sessionIndex: string,
+  ): Promise<void> {
+    try {
+      await this.redisService.del(`saml:session:${userId}:${connectionId}`);
+      await this.redisService.del(this._sloReverseKey(connectionId, sessionIndex));
+    } catch {
+      this.logger.warn('Failed to clean up SAML session state during SLO', { userId, connectionId });
+    }
+  }
+
+  /**
+   * Clean up forward mapping by userId (used when sessionIndex is unknown).
+   */
+  private async _terminateSAMLSessionByUser(userId: string, connectionId: string): Promise<void> {
+    try {
+      const forwardKey = `saml:session:${userId}:${connectionId}`;
+      const forwardData = await this.redisService.get<{ sessionIndex: string; nameId: string }>(forwardKey);
+      await this.redisService.del(forwardKey);
+      if (forwardData?.sessionIndex) {
+        await this.redisService.del(this._sloReverseKey(connectionId, forwardData.sessionIndex));
+      }
+    } catch {
+      this.logger.warn('Failed to clean up SAML session by user during SLO', { userId, connectionId });
+    }
+  }
+
+  /**
+   * Extract the Issuer from a LogoutRequest (either base64 or deflated+base64).
+   */
+  private _extractIssuerFromLogoutRequest(
+    samlRequest: string,
+    binding: 'redirect' | 'post',
+  ): string | null {
+    try {
+      let xml: string;
+      if (binding === 'redirect') {
+        const compressed = Buffer.from(samlRequest, 'base64');
+        const zlib = require('zlib');
+        xml = zlib.inflateRawSync(compressed).toString('utf-8');
+      } else {
+        xml = Buffer.from(samlRequest, 'base64').toString('utf-8');
+      }
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { DOMParser } = require('@xmldom/xmldom');
+      const doc = new DOMParser().parseFromString(xml, 'text/xml');
+
+      const requestElements = doc.getElementsByTagNameNS('*', 'LogoutRequest');
+      if (requestElements.length === 0) return null;
+
+      const children = requestElements.item(0).childNodes;
+      for (let i = 0; i < children.length; i++) {
+        const child = children.item(i);
+        if (child.localName === 'Issuer') {
+          return child.textContent?.trim() || null;
+        }
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Build a LogoutResponse to send back to the IdP.
+   */
+  private _buildLogoutResponse(
+    connection: SAMLResolvedConnection,
+    inResponseTo: string,
+    binding: 'redirect' | 'post',
+    relayState?: string,
+  ): { url: string } {
+    const saml = this._getSamlifyModule();
+    const appDomain = this._getAppDomain();
+    const sloUrl = `https://${appDomain}/auth/saml/slo`;
+
+    const sp = saml.ServiceProvider({
+      entityID: connection.spEntityId,
+      authnRequestsSigned: connection.signRequests,
+      wantAssertionsSigned: connection.wantAssertionsSigned,
+      wantMessageSigned: true,
+      signingCert: process.env.SAML_SP_CERTIFICATE,
+      privateKey: process.env.SAML_SP_PRIVATE_KEY,
+      nameIDFormat: [connection.nameIdFormat],
+      assertionConsumerService: [{ Binding: SAML_BINDINGS.POST, Location: connection.acsUrl }],
+      singleLogoutService: [
+        { Binding: SAML_BINDINGS.REDIRECT, Location: sloUrl },
+        { Binding: SAML_BINDINGS.POST, Location: sloUrl },
+      ],
+    });
+
+    const idp = saml.IdentityProvider({
+      entityID: connection.idpEntityId,
+      singleSignOnService: [{ Binding: SAML_BINDINGS.REDIRECT, Location: connection.ssoUrl }],
+      singleLogoutService: connection.sloUrl
+        ? [{ Binding: SAML_BINDINGS.REDIRECT, Location: connection.sloUrl },
+           { Binding: SAML_BINDINGS.POST, Location: connection.sloUrl }]
+        : [],
+      signingCert: connection.x509Certificates[0],
+      nameIDFormat: [connection.nameIdFormat],
+    });
+
+    const responseContext = sp.createLogoutResponse(
+      idp,
+      { id: inResponseTo },
+      binding,
+      relayState || '',
+    ) as { context: string; id: string };
+
+    return { url: responseContext.context };
+  }
+
+  private _sloReverseKey(connectionId: string, sessionIndex: string): string {
+    const hash = createHash('sha256').update(`${connectionId}:${sessionIndex}`).digest('hex');
+    return `saml:slo:idx:${hash}`;
+  }
+
+  private _emitSLOAudit(
+    connection: SAMLResolvedConnection,
+    sessionIndex: string | undefined,
+    direction: 'idp-initiated' | 'sp-initiated',
+    result: 'success' | 'no-session',
+  ): void {
+    const eventType = direction === 'sp-initiated'
+      ? CoreAuditableEventType.SAML_SLO_INITIATED
+      : CoreAuditableEventType.SAML_SLO_COMPLETED;
+
+    this.auditLogsService.logSAMLEvent(
+      eventType,
+      ResourceOperationRiskLevel.LOW,
+      {
+        connectionId: connection.organization?.connectionId,
+        idpEntityId: connection.idpEntityId,
+        sessionIndex,
+        direction,
+        result,
+        organizationId: connection.organization?.organizationId,
+        authSource: AuthSource.SAML,
+      },
+    ).catch(() => { /* fire-and-forget */ });
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Connection Resolution (D14)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Resolve the SAML connection from either the RelayState (SP-initiated)
+   * or the Response Issuer (IdP-initiated).
+   */
+  private async _resolveConnection(
+    ec: ExecutionContext<any>,
+    samlResponse: string,
+    relayState: string | undefined,
+    appDomain: string,
+  ): Promise<ConnectionResolutionResult> {
+    if (relayState) {
+      const spResult = await this._tryResolveConnectionSPInitiated(ec, relayState, samlResponse, appDomain);
+      if (spResult) return spResult;
+    }
+
+    return this._resolveConnectionIdPInitiated(ec, samlResponse, appDomain);
+  }
+
+  /**
+   * SP-initiated: consume the RelayState as a SAML_AUTH_STATE ConsumableToken,
+   * extract state metadata, load connection by connectionId, validate Issuer match.
+   *
+   * Returns null if the RelayState is not a valid SAML_AUTH_STATE token
+   * (falls through to IdP-initiated resolution).
+   */
+  private async _tryResolveConnectionSPInitiated(
+    ec: ExecutionContext<any>,
+    relayState: string,
+    samlResponse: string,
+    appDomain: string,
+  ): Promise<ConnectionResolutionResult | null> {
+    try {
+      const consumedToken = await this.consumableTokenService.consumeToken(relayState);
+
+      if (consumedToken.tokenType !== CoreConsumableTokenTypes.SAML_AUTH_STATE) {
+        return null;
+      }
+
+      const stateMetadata = consumedToken.metadata as unknown as SAMLStateMetadata;
+      const { connection, scopeType, scopeId } = await this._loadConnectionFromAnyScope(ec, stateMetadata.connectionId);
+
+      if (connection.protocol !== SsoProtocol.SAML || !connection.saml) {
+        throw this._buildAuthError(
+          ErrorCustomMessageReference.SAML_ASSERTION_INVALID,
+          'Connection resolved from state token is not SAML',
+        );
+      }
+
+      const issuer = this._extractIssuerFromResponse(samlResponse);
+      if (issuer && issuer !== connection.saml.entityId) {
+        this.logger.warn('SAML Response Issuer does not match connection entityId', {
+          expected: connection.saml.entityId,
+          received: issuer,
+        });
+        throw this._buildAuthError(
+          ErrorCustomMessageReference.SAML_ASSERTION_INVALID,
+          'SAML Response Issuer does not match the expected IdP',
+        );
+      }
+
+      const resolvedConnection = this._buildResolvedConnection(connection, scopeType, scopeId, appDomain);
+
+      return { resolvedConnection, stateMetadata, scopeType, scopeId };
+    } catch (error) {
+      if (isWildoBackendError(error)) throw error;
+      this.logDebug('RelayState is not a valid SAML state token, trying IdP-initiated path', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  /**
+   * IdP-initiated: parse the Issuer from the SAML Response, search for
+   * a matching SsoConnection globally by `saml.entityId`.
+   *
+   * Enforces: one match only, `allowIdpInitiated === true`.
+   */
+  private async _resolveConnectionIdPInitiated(
+    ec: ExecutionContext<any>,
+    samlResponse: string,
+    appDomain: string,
+  ): Promise<ConnectionResolutionResult> {
+    const issuer = this._extractIssuerFromResponse(samlResponse);
+    if (!issuer) {
+      throw this._buildAuthError(
+        ErrorCustomMessageReference.SAML_UNKNOWN_IDP,
+        'Cannot extract Issuer from SAML Response',
+      );
+    }
+
+    const matches = await this._findConnectionsByEntityId(ec, issuer);
+
+    if (matches.length === 0) {
+      throw this._buildAuthError(
+        ErrorCustomMessageReference.SAML_UNKNOWN_IDP,
+        'No SSO connection found for IdP entity ID',
+      );
+    }
+
+    if (matches.length > 1) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.SAML_AMBIGUOUS_IDP,
+        context: {
+          message: 'Multiple SSO connections match this IdP entity ID — use SP-initiated login',
+          entityId: issuer,
+          matchCount: matches.length,
+        },
+      });
+    }
+
+    const { connection, scopeType, scopeId } = matches[0];
+
+    if (!connection.saml!.allowIdpInitiated) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.SAML_IDP_INITIATED_NOT_ALLOWED,
+        context: {
+          message: 'IdP-initiated SAML login is not enabled for this connection',
+          connectionId: connection._id,
+        },
+      });
+    }
+
+    const resolvedConnection = this._buildResolvedConnection(connection, scopeType, scopeId, appDomain);
+
+    return { resolvedConnection, scopeType, scopeId };
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // SAML Response Parsing (Multi-Cert Rotation — SC-14)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Parse the SAML Response using samlify, trying each configured IdP
+   * certificate in sequence. Supports cert rotation where the signing
+   * cert changes before the admin updates config.
+   */
+  private async _parseSAMLResponseWithMultiCert(
+    connection: SAMLResolvedConnection,
+    samlResponse: string,
+  ): Promise<SamlifyParsedResponse & { validatingCertIndex: number }> {
+    const saml = this._getSamlifyModule();
+    let lastError: unknown;
+
+    for (let certIndex = 0; certIndex < connection.x509Certificates.length; certIndex++) {
+      const cert = connection.x509Certificates[certIndex];
+      try {
+        const sp = saml.ServiceProvider({
+          entityID: connection.spEntityId,
+          authnRequestsSigned: connection.signRequests,
+          wantAssertionsSigned: connection.wantAssertionsSigned,
+          wantMessageSigned: true,
+          signingCert: process.env.SAML_SP_CERTIFICATE,
+          privateKey: connection.signRequests ? process.env.SAML_SP_PRIVATE_KEY : undefined,
+          encPrivateKey: process.env.SAML_SP_PRIVATE_KEY,
+          nameIDFormat: [connection.nameIdFormat],
+          assertionConsumerService: [{ Binding: SAML_BINDINGS.POST, Location: connection.acsUrl }],
+        });
+
+        const idp = saml.IdentityProvider({
+          entityID: connection.idpEntityId,
+          singleSignOnService: [{ Binding: SAML_BINDINGS.REDIRECT, Location: connection.ssoUrl }],
+          signingCert: cert,
+          nameIDFormat: [connection.nameIdFormat],
+        });
+
+        const result = await sp.parseLoginResponse(idp, 'post', {
+          body: { SAMLResponse: samlResponse },
+        });
+
+        this.logDebug('SAML Response parsed and signature verified', {
+          idpEntityId: connection.idpEntityId,
+          certIndex,
+          totalCerts: connection.x509Certificates.length,
+        });
+
+        return { ...(result as SamlifyParsedResponse), validatingCertIndex: certIndex };
+      } catch (error) {
+        lastError = error;
+        if (this._isDecryptionError(error)) {
+          throw this._classifyDecryptionError(error);
+        }
+      }
+    }
+
+    this.logger.error('SAML signature verification failed with all configured certificates', {
+      idpEntityId: connection.idpEntityId,
+      certCount: connection.x509Certificates.length,
+      lastError: lastError instanceof Error ? lastError.message : String(lastError),
+    });
+
+    throw this._buildAuthError(
+      ErrorCustomMessageReference.SAML_SIGNATURE_INVALID,
+      'SAML Response signature verification failed',
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // User Profile Extraction (E17)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Extract a NormalizedUserProfile from validated SAML assertion data
+   * using the connection's attribute mapping configuration.
+   *
+   * Resolution order per attribute (E17):
+   * 1. Exact URI match from configured mapping
+   * 2. Case-insensitive friendly name match
+   * 3. Common alternative URIs/OIDs
+   */
+  private _extractUserProfileFromAssertion(
+    assertionData: SAMLAssertionData,
+    connection: SAMLResolvedConnection,
+  ): NormalizedUserProfile {
+    const attrs = assertionData.attributes;
+    const mapping = connection.attributeMapping;
+
+    const email = this._extractMappedAttribute(attrs, mapping['email'] || mapping['Email'], 'email');
+    const firstName = this._extractMappedAttribute(attrs, mapping['firstName'], 'firstName');
+    const lastName = this._extractMappedAttribute(attrs, mapping['lastName'], 'lastName');
+    const rolesRaw = this._extractMappedAttribute(attrs, mapping['roles'], 'roles');
+    const department = this._extractMappedAttribute(attrs, mapping['department'], 'department');
+    const employeeId = this._extractMappedAttribute(attrs, mapping['employeeId'], 'employeeId');
+    const groupsRaw = this._extractMappedAttribute(attrs, mapping['groups'], 'groups');
+
+    const roles = rolesRaw ? this._parseArrayAttribute(attrs, mapping['roles'] || '', 'roles') : undefined;
+    const groups = groupsRaw ? this._parseArrayAttribute(attrs, mapping['groups'] || '', 'groups') : undefined;
+
+    const displayName = [firstName, lastName].filter(Boolean).join(' ') || assertionData.nameId;
+
+    if (!email) {
+      throw this._buildAuthError(
+        ErrorCustomMessageReference.SAML_ASSERTION_INVALID,
+        'Required attribute "email" not found in SAML assertion',
+      );
+    }
+
+    return {
+      providerUserId: '', // set by caller after derivation (D15, E29)
+      email: email.toLowerCase(),
+      emailVerified: true, // enterprise IdP is trusted for email verification
+      firstName: firstName || undefined,
+      lastName: lastName || undefined,
+      displayName: displayName || undefined,
+      roles,
+      groups,
+      department: department || undefined,
+      employeeId: employeeId || undefined,
+      rawClaims: attrs as Record<string, unknown>,
+    };
+  }
+
+  /**
+   * Resolve a single attribute value from the assertion using the
+   * three-tier fallback strategy (E17).
+   */
+  private _extractMappedAttribute(
+    attributes: Record<string, string | string[]>,
+    configuredUri: string | undefined,
+    fieldName: string,
+  ): string | undefined {
+    if (!configuredUri) {
+      return this._tryAlternativeAttributes(attributes, fieldName);
+    }
+
+    // Tier 1: Exact URI match
+    const exactValue = this._resolveAttributeValue(attributes, configuredUri);
+    if (exactValue) {
+      this.logDebug(`Attribute "${fieldName}" resolved via exact match`, { uri: configuredUri });
+      return exactValue;
+    }
+
+    // Tier 2: Case-insensitive friendly name match
+    const lowerUri = configuredUri.toLowerCase();
+    for (const [key, val] of Object.entries(attributes)) {
+      if (key.toLowerCase() === lowerUri) {
+        const resolved = Array.isArray(val) ? val[0] : val;
+        if (resolved) {
+          this.logDebug(`Attribute "${fieldName}" resolved via case-insensitive match`, { key });
+          return resolved;
+        }
+      }
+    }
+
+    // Tier 3: Common alternatives
+    return this._tryAlternativeAttributes(attributes, fieldName);
+  }
+
+  private _tryAlternativeAttributes(
+    attributes: Record<string, string | string[]>,
+    fieldName: string,
+  ): string | undefined {
+    const alternatives = COMMON_ATTRIBUTE_ALTERNATIVES[fieldName];
+    if (!alternatives) return undefined;
+
+    for (const alt of alternatives) {
+      const value = this._resolveAttributeValue(attributes, alt);
+      if (value) {
+        this.logDebug(`Attribute "${fieldName}" resolved via alternative`, { uri: alt });
+        return value;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Parse an attribute as an array (for roles, groups).
+   * Handles both string[] and comma-separated string values.
+   */
+  private _parseArrayAttribute(
+    attributes: Record<string, string | string[]>,
+    configuredUri: string,
+    fieldName: string,
+  ): string[] | undefined {
+    const raw = attributes[configuredUri];
+    if (!raw) {
+      const alternatives = COMMON_ATTRIBUTE_ALTERNATIVES[fieldName];
+      if (alternatives) {
+        for (const alt of alternatives) {
+          const altRaw = attributes[alt];
+          if (altRaw) {
+            return Array.isArray(altRaw) ? altRaw : altRaw.split(',').map(s => s.trim());
+          }
+        }
+      }
+      return undefined;
+    }
+    return Array.isArray(raw) ? raw : raw.split(',').map(s => s.trim());
+  }
+
+  private _resolveAttributeValue(
+    attributes: Record<string, string | string[]>,
+    uri: string,
+  ): string | undefined {
+    const value = attributes[uri];
+    if (!value) return undefined;
+    return Array.isArray(value) ? value[0] : value;
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Connection Loading
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Load an SSO connection by ID, trying both organization and application scopes.
+   * The connection's polymorphic FK field (`organizationId` / `applicationId`)
+   * determines the scope context.
+   */
+  private async _loadConnectionFromAnyScope(
+    ec: ExecutionContext<any>,
+    connectionId: string,
+  ): Promise<{ connection: SsoConnectionBase; scopeType: string; scopeId: string }> {
+    const resourceTypes = [
+      { type: CoreResourceType.ORGANIZATION_SSO_CONNECTIONS, scopeKey: 'organizationId', scopeType: AuthScopeType.ORGANIZATION },
+      { type: CoreResourceType.APPLICATION_SSO_CONNECTIONS, scopeKey: 'applicationId', scopeType: AuthScopeType.APPLICATION },
+    ];
+
+    for (const { type, scopeKey, scopeType } of resourceTypes) {
+      try {
+        const connection = await this.servicesRegistryHandler.read<SsoConnectionBase>(type, ec, { _id: connectionId });
+        if (connection) {
+          const scopeId = (connection as SsoConnectionWithScope)[scopeKey];
+          if (scopeId) {
+            return { connection, scopeType, scopeId };
+          }
+        }
+      } catch (error) {
+        if (isWildoBackendError(error)) {
+          // Not-found errors from read() are expected — continue to next scope
+          const errorRef = error.customMessageReference;
+          if (errorRef && errorRef !== ErrorCustomMessageReference.NOT_FOUND) {
+            throw error;
+          }
+        }
+      }
+    }
+
+    throw this._buildAuthError(
+      ErrorCustomMessageReference.SAML_ASSERTION_INVALID,
+      `SSO connection not found: ${connectionId}`,
+    );
+  }
+
+  /**
+   * Find all SsoConnections whose `saml.entityId` matches the given issuer.
+   * Searches both organization and application scopes for IdP-initiated resolution (D14).
+   */
+  private async _findConnectionsByEntityId(
+    ec: ExecutionContext<any>,
+    entityId: string,
+  ): Promise<Array<{ connection: SsoConnectionBase; scopeType: string; scopeId: string }>> {
+    const results: Array<{ connection: SsoConnectionBase; scopeType: string; scopeId: string }> = [];
+
+    const resourceTypes = [
+      { type: CoreResourceType.ORGANIZATION_SSO_CONNECTIONS, scopeKey: 'organizationId', scopeType: AuthScopeType.ORGANIZATION },
+      { type: CoreResourceType.APPLICATION_SSO_CONNECTIONS, scopeKey: 'applicationId', scopeType: AuthScopeType.APPLICATION },
+    ];
+
+    for (const { type, scopeKey, scopeType } of resourceTypes) {
+      try {
+        const connections = await this.servicesRegistryHandler.list<SsoConnectionBase>(type, ec, {
+          protocol: SsoProtocol.SAML,
+          'saml.entityId': entityId,
+          enabled: true,
+        } as Record<string, unknown>, undefined, { paginated: false }) as SsoConnectionBase[];
+
+        const connectionsList = connections ?? [];
+        for (const conn of connectionsList) {
+          const scopeId = (conn as SsoConnectionWithScope)[scopeKey];
+          if (scopeId) {
+            results.push({ connection: conn, scopeType, scopeId });
+          }
+        }
+      } catch (error) {
+        if (isWildoBackendError(error)) throw error;
+        this.logger.warn('Failed to search SSO connections by entityId', {
+          resourceType: type,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    return results;
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Resolved Connection Builder
+  // ═══════════════════════════════════════════════════════════════
+
+  private _buildResolvedConnection(
+    connection: SsoConnectionBase,
+    scopeType: string,
+    scopeId: string,
+    appDomain: string,
+  ): SAMLResolvedConnection {
+    const saml = connection.saml!;
+
+    const attributeMapping: Record<string, string> = {};
+    if (saml.attributeMapping) {
+      for (const [key, value] of Object.entries(saml.attributeMapping)) {
+        if (typeof value === 'string') {
+          attributeMapping[key] = value;
+        }
+      }
+    }
+
+    return {
+      source: SsoProtocol.SAML,
+      connectionType: SsoConnectionType.ENTERPRISE,
+      providerRef: connection.externalProviderId || connection._id,
+      displayName: connection.displayName,
+      organization: {
+        organizationId: scopeId,
+        connectionId: connection._id,
+        scopeType: scopeType as AuthScopeType,
+        scopeId,
+        autoCreateUsers: connection.autoCreateUsers,
+        autoVerifyEmail: connection.autoVerifyEmail,
+        defaultRole: connection.defaultRole,
+        roleMapping: connection.roleMapping,
+        groupMapping: connection.groupMapping,
+        allowedDomains: connection.allowedDomains,
+      },
+      idpEntityId: saml.entityId,
+      ssoUrl: saml.ssoUrl,
+      sloUrl: saml.sloUrl,
+      x509Certificates: saml.x509Certificates,
+      spEntityId: `https://${appDomain}/saml/sp/${scopeType}/${scopeId}`,
+      acsUrl: `https://${appDomain}/auth/saml/acs`,
+      nameIdFormat: saml.nameIdFormat,
+      attributeMapping,
+      allowIdpInitiated: saml.allowIdpInitiated,
+      allowedClockDrift: saml.allowedClockDrift,
+      signRequests: saml.signRequests,
+      wantAssertionsSigned: saml.wantAssertionsSigned,
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // XML / Issuer Extraction
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Lightweight extraction of the Response-level `<Issuer>` element
+   * from a base64-encoded SAML Response. Used before full samlify
+   * parsing for IdP-initiated connection resolution and SP-initiated
+   * Issuer validation.
+   */
+  private _extractIssuerFromResponse(samlResponseBase64: string): string | null {
+    try {
+      const xml = Buffer.from(samlResponseBase64, 'base64').toString('utf-8');
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { DOMParser } = require('@xmldom/xmldom');
+      const doc = new DOMParser().parseFromString(xml, 'text/xml');
+
+      const responseElements = doc.getElementsByTagNameNS('*', 'Response');
+      if (responseElements.length === 0) return null;
+
+      const children = responseElements.item(0).childNodes;
+      for (let i = 0; i < children.length; i++) {
+        const child = children.item(i);
+        if (child.localName === 'Issuer') {
+          return child.textContent?.trim() || null;
+        }
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // URL Validation (SC-26, E21)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Validate returnUrl to prevent open redirects via RelayState.
+   * Must be a relative path (`/...`) or match one of the configured frontend
+   * service origins.
+   */
+  private _validateReturnUrl(returnUrl: string, appDomain: string): void {
+    if (returnUrl.startsWith('/') && !returnUrl.startsWith('//')) return;
+
+    try {
+      const parsed = new URL(returnUrl);
+      const allowedOrigins = new Set<string>([`https://${appDomain}`]);
+      for (const frontendServiceName of Object.keys(this.appConfigService.config.frontendServices ?? {})) {
+        const publicUrl = AuthControllerUtils.lookupFrontendPublicUrl(
+          this.appConfigService.config,
+          frontendServiceName,
+        );
+        if (!publicUrl) {
+          continue;
+        }
+        allowedOrigins.add(new URL(publicUrl).origin);
+      }
+
+      if (allowedOrigins.has(parsed.origin)) return;
+    } catch { /* invalid URL — reject */ }
+
+    throw this._buildAuthError(
+      ErrorCustomMessageReference.SAML_ASSERTION_INVALID,
+      'Invalid returnUrl: must be a relative path or same-origin URL',
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Audit Helpers
+  // ═══════════════════════════════════════════════════════════════
+
+  private _emitFailureAudit(
+    connection: SAMLResolvedConnection,
+    failureReason: string,
+    clientContext?: { ipAddress: string; userAgent: string },
+  ): void {
+    this.auditLogsService.logUserSSOLoginFailed({
+      email: '',
+      providerRef: connection.providerRef,
+      connectionType: SsoConnectionType.ENTERPRISE,
+      authSource: AuthSource.SAML,
+      organizationId: connection.organization?.organizationId,
+      failureReason,
+      ipAddress: clientContext?.ipAddress || 'unknown',
+      userAgent: clientContext?.userAgent || 'unknown',
+    }).catch(() => { /* audit failure must not block error propagation */ });
+
+    this.auditLogsService.logSAMLEvent(
+      CoreAuditableEventType.SAML_LOGIN_FAILED,
+      ResourceOperationRiskLevel.MEDIUM,
+      {
+        connectionId: connection.organization?.connectionId,
+        idpEntityId: connection.idpEntityId,
+        errorReference: failureReason,
+        organizationId: connection.organization?.organizationId,
+        authSource: AuthSource.SAML,
+      },
+    ).catch(() => { /* fire-and-forget */ });
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Infrastructure Helpers
+  // ═══════════════════════════════════════════════════════════════
+
+  private _getAppDomain(): string {
+    const config = this.appConfigService.config;
+    const domain = process.env.APP_DOMAIN || config?.auth?.passkeyConfig?.rpId;
+    if (!domain) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.SAML_ASSERTION_INVALID,
+        context: { message: 'APP_DOMAIN environment variable must be set for SAML' },
+      });
+    }
+    return domain;
+  }
+
+  /**
+   * Pre-auth EC for SAML operations (ACS callback, SLO, SP-initiated logout).
+   * Caller identity unknown at this point — uses PUBLIC_EXECUTION with APP_PUBLIC.
+   * Primary intent: user lookup/provisioning from SAML assertion.
+   */
+  private async _getInternalExecutionContext(): Promise<ExecutionContext<any>> {
+    return this.authEcFactory.createForPreAuthOperation(this.authEcFactory.getUsersReadOperationPath());
+  }
+
+  // Returns `any` to avoid `typeof import('samlify')` which forces tsc to resolve the CJS-only samlify package during declaration emit.
+  private _getSamlifyModule(): any {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const saml = require('samlify');
+    if (!this.samlifyInitialized) {
+      const java = checkJavaAvailability();
+      if (!java.available) {
+        const msg =
+          'SAML XSD validation requires Java (JRE 8+). Install Java or set JAVA_HOME. ' +
+          'Docker: add openjdk17-jre-headless. Reason: ' + (java.reason ?? 'java not found');
+        if (isTestEnvironment()) {
+          this.logger.warn(`[SAML] ${msg} — tests may use mock parser (SAMLResponseParserOverride).`);
+        } else {
+          throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+            customMessageReference: ErrorCustomMessageReference.SAML_JAVA_REQUIRED,
+            context: { message: msg },
+          });
+        }
+      } else {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const validator = require('@authenio/samlify-xsd-schema-validator');
+        saml.setSchemaValidator(validator);
+        this.logDebug('samlify XSD schema validator initialized');
+      }
+      this.samlifyInitialized = true;
+    }
+    return saml;
+  }
+
+  private _buildAuthError(
+    ref: ErrorCustomMessageReference,
+    message: string,
+    extra?: Record<string, unknown>,
+  ): ReturnType<ErrorBuilderBackendService['buildError']> {
+    return this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+      customMessageReference: ref,
+      context: { message, ...extra },
+    });
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Encrypted Assertion Decryption Error Classification (E28, SC-31, SC-32)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Detect whether a samlify error is a decryption failure.
+   * samlify throws errors with specific codes for assertion decryption failures.
+   */
+  private _isDecryptionError(error: unknown): boolean {
+    if (!(error instanceof Error)) return false;
+    const msg = error.message.toLowerCase();
+    return msg.includes('decrypt') ||
+      msg.includes('encryption') ||
+      msg.includes('ERR_EXCEPTION_OF_ASSERTION_DECRYPTION'.toLowerCase()) ||
+      msg.includes('encryptedassertion') ||
+      msg.includes('pkcs') ||
+      msg.includes('err_ossl');
+  }
+
+  /**
+   * Classify a decryption error into a specific error type:
+   * - Key mismatch: SP private key doesn't match the encryption certificate
+   * - Algorithm unsupported: IdP used an encryption algorithm we don't support
+   * - Generic: other decryption failures
+   */
+  private _classifyDecryptionError(error: unknown): ReturnType<ErrorBuilderBackendService['buildError']> {
+    const msg = error instanceof Error ? error.message : String(error);
+    const msgLower = msg.toLowerCase();
+
+    if (msgLower.includes('key') || msgLower.includes('pkcs') || msgLower.includes('err_ossl_rsa') || msgLower.includes('padding')) {
+      return this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.SAML_SP_KEY_MISMATCH,
+        context: { message: 'SP private key does not match the encryption certificate.' },
+      });
+    }
+
+    if (msgLower.includes('algorithm') || msgLower.includes('unsupported') || msgLower.includes('err_ossl_evp')) {
+      const algorithmMatch = msg.match(/algorithm[:\s]*([^\s,]+)/i);
+      return this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.SAML_UNSUPPORTED_ENCRYPTION,
+        context: {
+          message: `Unsupported encryption algorithm${algorithmMatch ? `: ${algorithmMatch[1]}` : ''}`,
+        },
+      });
+    }
+
+    return this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+      customMessageReference: ErrorCustomMessageReference.SAML_DECRYPTION_FAILED,
+      context: { message: 'Failed to decrypt SAML assertion.' },
+    });
+  }
+}