@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/security/authentications/services/auth-methods/saml-authentication.backend.service.js

@@ -0,0 +1,1376 @@
+/**
+ * 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)
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+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 '../../../../inject/models/service-types.js';
+import { LoggerService } from '../../../../monitoring/logger/services/logger.service.js';
+import { AppConfigurationService } from '../../../../config/services/app-configuration.backend.service.js';
+import { ErrorBuilderBackendService } from '../../../../errors/services/error-builder.backend.service.js';
+import { AuthUserLookupBackendService } from '../../../../security/authentications/services/utils/auth-user-lookup.backend.service.js';
+import { AuthExecutionContextFactoryBackendService } from '../../../../security/authentications/services/auth-execution-context-factory.backend.service.js';
+import { ConsumableTokenBackendService } from '../../../../security/consumable-tokens/services/consumable-token.backend.service.js';
+import { SAMLAssertionValidatorBackendService } from './saml-assertion-validator.backend.service.js';
+import { SAMLMetadataBackendService } from './saml-metadata.backend.service.js';
+import { DomainToOrgLookupBackendService } from '../../../../security/authentications/services/admin-config/domain-to-org-lookup.backend.service.js';
+import { EnterpriseUserProvisioningBackendService } from '../../../../security/authentications/services/admin-config/enterprise-user-provisioning.backend.service.js';
+import { AuthControllerUtils } from '../../../../security/authentications/services/utils/auth-controller.utils.js';
+import { AuditLogsBackendService } from '../../../../compliance/audit-trails/services/audit-logs.backend.service.js';
+import { AuthTokenIssuerBackendService } from '../../../../security/authentications/services/auth-token-issuer.backend.service.js';
+import { RedisService } from '../../../../databases/services/redis.service.js';
+import { checkJavaAvailability, isTestEnvironment, } from '../../../../security/authentications/services/utils/saml-java-availability.js';
+import { AuthSource, SsoProtocol } from '../../../../security/authentications/models/auth-constants.backend.js';
+import { CoreConsumableTokenTypes, ConsumableToken_ConsumptionMode, CoreResourceType, CoreAuditableEventType, ResourceOperationRiskLevel, ErrorType, ErrorCustomMessageReference, isWildoBackendError, SsoConnectionType, AuthScopeType, UserStatus, } from '@wildo-ai/saas-models';
+import { DurationUnit } from '@wildo-ai/zod-decorators';
+// ─────────────────────────────────────────────────────────────────
+// 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',
+};
+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 = {
+    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',
+    ],
+};
+// ─────────────────────────────────────────────────────────────────
+// Service
+// ─────────────────────────────────────────────────────────────────
+let SAMLAuthenticationBackendService = class SAMLAuthenticationBackendService {
+    logger;
+    appConfigService;
+    errorBuilder;
+    servicesRegistryHandler;
+    userLookup;
+    authEcFactory;
+    consumableTokenService;
+    assertionValidator;
+    metadataService;
+    domainToOrgLookup;
+    enterpriseProvisioning;
+    auditLogsService;
+    tokenIssuer;
+    redisService;
+    samlResponseParserOverride;
+    logDebug;
+    samlifyInitialized = false;
+    constructor(logger, appConfigService, errorBuilder, servicesRegistryHandler, userLookup, authEcFactory, consumableTokenService, assertionValidator, metadataService, domainToOrgLookup, enterpriseProvisioning, auditLogsService, tokenIssuer, redisService, samlResponseParserOverride) {
+        this.logger = logger;
+        this.appConfigService = appConfigService;
+        this.errorBuilder = errorBuilder;
+        this.servicesRegistryHandler = servicesRegistryHandler;
+        this.userLookup = userLookup;
+        this.authEcFactory = authEcFactory;
+        this.consumableTokenService = consumableTokenService;
+        this.assertionValidator = assertionValidator;
+        this.metadataService = metadataService;
+        this.domainToOrgLookup = domainToOrgLookup;
+        this.enterpriseProvisioning = enterpriseProvisioning;
+        this.auditLogsService = auditLogsService;
+        this.tokenIssuer = tokenIssuer;
+        this.redisService = redisService;
+        this.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
+     */
+    async initiateLogin(ec, connectionId, returnUrl) {
+        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 = loginRequest.id;
+        const redirectContext = 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(),
+            },
+        });
+        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(() => { });
+        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
+     */
+    async handleACS(ec, samlResponse, relayState, clientContext) {
+        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 = await this.servicesRegistryHandler.list(CoreResourceType.USER_IDENTITY_LINKS, ec, { userId: existingUser._id, connectionType: 'enterprise' }, undefined, { paginated: false }) ?? [];
+                    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(() => { });
+            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)
+     */
+    async handleIdPInitiatedSLO(ec, binding, samlRequest, relayState) {
+        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;
+        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 = extract?.logoutRequest?.sessionIndex ?? extract?.sessionIndex;
+        const nameId = extract?.logoutRequest?.nameID ?? extract?.nameID;
+        const requestId = extract?.logoutRequest?.id ?? extract?.request?.id;
+        let terminatedUserId;
+        let sloResult = '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).
+     */
+    async initiateSPLogout(ec, userId, connectionId) {
+        const internalEc = await this._getInternalExecutionContext();
+        const appDomain = this._getAppDomain();
+        let connection;
+        let scopeType;
+        let scopeId;
+        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(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 });
+        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.
+     */
+    async handleSLOResponse(ec, binding, samlResponse) {
+        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).
+     */
+    async _parseSLORequestWithMultiCert(connection, binding, samlRequest) {
+        const saml = this._getSamlifyModule();
+        const appDomain = this._getAppDomain();
+        const sloUrl = `https://${appDomain}/auth/saml/slo`;
+        let lastError;
+        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;
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw lastError || new Error('SLO request parsing failed');
+    }
+    /**
+     * Find the userId for a given SessionIndex via the reverse mapping.
+     */
+    async _findSessionByIndex(connectionId, sessionIndex) {
+        try {
+            const reverseKey = this._sloReverseKey(connectionId, sessionIndex);
+            return await this.redisService.get(reverseKey);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Clean up SAML session state in Redis: forward + reverse mappings.
+     */
+    async _terminateSAMLSession(userId, connectionId, sessionIndex) {
+        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).
+     */
+    async _terminateSAMLSessionByUser(userId, connectionId) {
+        try {
+            const forwardKey = `saml:session:${userId}:${connectionId}`;
+            const forwardData = await this.redisService.get(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).
+     */
+    _extractIssuerFromLogoutRequest(samlRequest, binding) {
+        try {
+            let xml;
+            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.
+     */
+    _buildLogoutResponse(connection, inResponseTo, binding, relayState) {
+        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 || '');
+        return { url: responseContext.context };
+    }
+    _sloReverseKey(connectionId, sessionIndex) {
+        const hash = createHash('sha256').update(`${connectionId}:${sessionIndex}`).digest('hex');
+        return `saml:slo:idx:${hash}`;
+    }
+    _emitSLOAudit(connection, sessionIndex, direction, result) {
+        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(() => { });
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Connection Resolution (D14)
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Resolve the SAML connection from either the RelayState (SP-initiated)
+     * or the Response Issuer (IdP-initiated).
+     */
+    async _resolveConnection(ec, samlResponse, relayState, appDomain) {
+        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).
+     */
+    async _tryResolveConnectionSPInitiated(ec, relayState, samlResponse, appDomain) {
+        try {
+            const consumedToken = await this.consumableTokenService.consumeToken(relayState);
+            if (consumedToken.tokenType !== CoreConsumableTokenTypes.SAML_AUTH_STATE) {
+                return null;
+            }
+            const stateMetadata = consumedToken.metadata;
+            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`.
+     */
+    async _resolveConnectionIdPInitiated(ec, samlResponse, appDomain) {
+        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.
+     */
+    async _parseSAMLResponseWithMultiCert(connection, samlResponse) {
+        const saml = this._getSamlifyModule();
+        let lastError;
+        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, 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
+     */
+    _extractUserProfileFromAssertion(assertionData, connection) {
+        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,
+        };
+    }
+    /**
+     * Resolve a single attribute value from the assertion using the
+     * three-tier fallback strategy (E17).
+     */
+    _extractMappedAttribute(attributes, configuredUri, fieldName) {
+        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);
+    }
+    _tryAlternativeAttributes(attributes, fieldName) {
+        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.
+     */
+    _parseArrayAttribute(attributes, configuredUri, fieldName) {
+        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());
+    }
+    _resolveAttributeValue(attributes, uri) {
+        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.
+     */
+    async _loadConnectionFromAnyScope(ec, connectionId) {
+        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(type, ec, { _id: connectionId });
+                if (connection) {
+                    const scopeId = connection[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).
+     */
+    async _findConnectionsByEntityId(ec, entityId) {
+        const results = [];
+        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(type, ec, {
+                    protocol: SsoProtocol.SAML,
+                    'saml.entityId': entityId,
+                    enabled: true,
+                }, undefined, { paginated: false });
+                const connectionsList = connections ?? [];
+                for (const conn of connectionsList) {
+                    const scopeId = conn[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
+    // ═══════════════════════════════════════════════════════════════
+    _buildResolvedConnection(connection, scopeType, scopeId, appDomain) {
+        const saml = connection.saml;
+        const attributeMapping = {};
+        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,
+                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.
+     */
+    _extractIssuerFromResponse(samlResponseBase64) {
+        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.
+     */
+    _validateReturnUrl(returnUrl, appDomain) {
+        if (returnUrl.startsWith('/') && !returnUrl.startsWith('//'))
+            return;
+        try {
+            const parsed = new URL(returnUrl);
+            const allowedOrigins = new Set([`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
+    // ═══════════════════════════════════════════════════════════════
+    _emitFailureAudit(connection, failureReason, clientContext) {
+        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(() => { });
+        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(() => { });
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Infrastructure Helpers
+    // ═══════════════════════════════════════════════════════════════
+    _getAppDomain() {
+        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.
+     */
+    async _getInternalExecutionContext() {
+        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.
+    _getSamlifyModule() {
+        // 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;
+    }
+    _buildAuthError(ref, message, extra) {
+        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.
+     */
+    _isDecryptionError(error) {
+        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
+     */
+    _classifyDecryptionError(error) {
+        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.' },
+        });
+    }
+};
+SAMLAuthenticationBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.AppConfigService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.AuthUserLookupService)),
+    __param(5, inject(SAAS_SERVICE_TYPES.AuthExecutionContextFactory)),
+    __param(6, inject(SAAS_SERVICE_TYPES.ConsumableTokenService)),
+    __param(7, inject(SAAS_SERVICE_TYPES.SAMLAssertionValidatorService)),
+    __param(8, inject(SAAS_SERVICE_TYPES.SAMLMetadataService)),
+    __param(9, inject(SAAS_SERVICE_TYPES.DomainToOrgLookupService)),
+    __param(10, inject(SAAS_SERVICE_TYPES.EnterpriseUserProvisioningService)),
+    __param(11, inject(SAAS_SERVICE_TYPES.AuditLogsService)),
+    __param(12, inject(SAAS_SERVICE_TYPES.AuthTokenIssuer)),
+    __param(13, inject(SAAS_SERVICE_TYPES.RedisService)),
+    __param(14, inject(SAAS_SERVICE_TYPES.SAMLResponseParserOverride)),
+    __param(14, optional()),
+    __metadata("design:paramtypes", [LoggerService,
+        AppConfigurationService,
+        ErrorBuilderBackendService, Function, AuthUserLookupBackendService,
+        AuthExecutionContextFactoryBackendService,
+        ConsumableTokenBackendService,
+        SAMLAssertionValidatorBackendService,
+        SAMLMetadataBackendService,
+        DomainToOrgLookupBackendService,
+        EnterpriseUserProvisioningBackendService,
+        AuditLogsBackendService,
+        AuthTokenIssuerBackendService,
+        RedisService, Object])
+], SAMLAuthenticationBackendService);
+export { SAMLAuthenticationBackendService };
+//# sourceMappingURL=saml-authentication.backend.service.js.map