@wildo-ai/saas-backend-lib 1.0.1

package/src/security/authentications/services/auth-methods/oauth2-connection-resolver.backend.service.ts

@@ -0,0 +1,903 @@
+/**
+ * OAuth2ConnectionResolverBackendService
+ *
+ * Resolves OAuth2 connection configurations from multiple sources:
+ * - Provider definitions from the external-connectors catalog (AllProviders_Map)
+ * - App-specific SSO config from AppConfiguration.auth.ssoProviders
+ * - Client credentials from AppConfiguration.externalProvidersConfigurations + secrets
+ *
+ * Produces an `OAuth2ResolvedConnection` — the canonical input for the OAuth2 engine.
+ *
+ * Step 4: Implements `resolveSocialConnection()` (fully functional)
+ * Step 15: Implements `resolveEnterpriseConnection()` (template/discovery/manual branching)
+ *
+ * [Capacitor] [OAuth2] [SAML]
+ * The redirect URI derived from runtime.endPoints.main_backend_api.publicUrl is the
+ * registered OAuth2 callback URL at IdPs. This remains unchanged for Capacitor — the
+ * IdP always redirects to the backend, not to the frontend. The Capacitor impact is only
+ * on the frontend→IdP navigation and the backend→frontend final redirect (deep links).
+ */
+
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+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 { ExternalProvidersRegistryBackendService } from '~wildo-backend-lib/external-providers/services/external-providers-registry.backend.service';
+import { AuthOrganizationConfigurationService } from '~wildo-backend-lib/security/authentications/services/admin-config/auth-organization-configuration.service';
+import { OIDCDiscoveryBackendService } from '~wildo-backend-lib/security/authentications/services/admin-config/oidc-discovery.backend.service';
+import {
+  ErrorType,
+  ErrorCustomMessageReference,
+  CoreResourceType,
+  AuthScopeType,
+  isWildoBackendError,
+} from '@wildo-ai/saas-models';
+import type { SsoConnectionBase } from '@wildo-ai/saas-models';
+import { SsoProtocol } from '~wildo-backend-lib/security/authentications/models/auth-constants.backend';
+import { AllProviders_Map, } from '@wildo-ai/external-connectors';
+import { ExternalProvider_ExchangeProtocol_Kind } from '@wildo-ai/external-connectors-models';
+import type { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';
+import type {
+  OAuth2ResolvedConnection,
+  OAuth2ProfileMapping,
+  OAuth2StateTokenMetadata,
+} from '~wildo-backend-lib/security/authentications/models/oauth2-connection.backend.schemas';
+import type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import jwt from 'jsonwebtoken';
+
+// ═══════════════════════════════════════════════════════════════
+// Signed JWT Client Secret — Generic (extensions-driven)
+// ═══════════════════════════════════════════════════════════════
+
+interface SignedJwtClientSecretParams {
+  privateKey: string;
+  keyId: string;
+  teamId: string;
+  clientId: string;
+  algorithm: string;
+  audience: string;
+  maxLifetimeSeconds: number;
+}
+
+const signedJwtCache = new Map<string, { jwt: string; expiresAt: number }>();
+const SIGNED_JWT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+function getOrGenerateSignedJwtClientSecret(
+  providerRef: string,
+  clientId: string,
+  params: SignedJwtClientSecretParams,
+): string {
+  const cacheKey = `${providerRef}:${clientId}`;
+  const cached = signedJwtCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.jwt;
+  }
+
+  const token = jwt.sign({}, params.privateKey, {
+    algorithm: params.algorithm as jwt.Algorithm,
+    keyid: params.keyId,
+    issuer: params.teamId,
+    audience: params.audience,
+    subject: params.clientId,
+    expiresIn: params.maxLifetimeSeconds,
+  });
+
+  signedJwtCache.set(cacheKey, { jwt: token, expiresAt: Date.now() + SIGNED_JWT_CACHE_TTL_MS });
+  return token;
+}
+
+/**
+ * Resolves OAuth2 connection configurations for social and enterprise SSO.
+ * The engine (OAuth2AuthenticationBackendService) never reads from AllProviders_Map
+ * or AppConfiguration directly — it only operates on OAuth2ResolvedConnection.
+ */
+@injectable()
+export class OAuth2ConnectionResolverBackendService {
+  private readonly logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  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.ExternalProvidersRegistryService) private readonly externalProvidersRegistry: ExternalProvidersRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthOrganizationConfigurationService) private readonly orgConfigService: AuthOrganizationConfigurationService,
+    @inject(SAAS_SERVICE_TYPES.OIDCDiscoveryService) private readonly oidcDiscovery: OIDCDiscoveryBackendService,
+    @inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService) private readonly servicesRegistryHandler: ServicesRegistryHandlerBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('OAuth2ConnectionResolver');
+    this.logger.setDebugTypeLogging('OAuth2ConnectionResolver', false);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Social Connection Resolution
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Resolve a social SSO connection from the provider catalog + app config + secrets.
+   *
+   * Resolution chain:
+   * 1. Look up provider definition from AllProviders_Map
+   * 2. Find the SSO_OAUTH2 protocol on the provider
+   * 3. Read app-specific SSO config from auth.ssoProviders[providerRef]
+   * 4. Read OAuth2 credentials from externalProvidersConfigurations[providerRef][sso_oauth2]
+   * 5. Resolve clientSecret from secrets store (app-level baseline)
+   * 5b. Check for org/app-level social credential overrides (P3)
+   * 5c. Generate signed-JWT client secret if provider requires it (e.g. Apple)
+   * 6. Derive redirectUri from publicUrl
+   * 7. Map profile fields, scopes, PKCE, response mode, identity source
+   *
+   * ORDERING CONSTRAINT (5b before 5c):
+   * Override credentials (5b) MUST be resolved before signed-JWT generation (5c).
+   * For providers like Apple, `clientSecret` is a raw private key that needs JWT signing.
+   * If 5c ran first, the override would replace the generated JWT with a raw key,
+   * causing the token exchange to fail at the IdP. By running 5b first, whichever
+   * private key is active (app-level or override) goes through JWT signing in 5c.
+   *
+   * @param providerRef - Provider identifier (e.g. 'google', 'apple')
+   * @param options.ec - Execution context, required when scopeId is set
+   * @param options.scopeType - 'organization' or 'application' (defaults to 'organization')
+   * @param options.scopeId - Org/app ID to check for credential overrides in SsoConfig
+   */
+  public async resolveSocialConnection(
+    providerRef: string,
+    options?: { ec?: ExecutionContext<any>; scopeType?: AuthScopeType; scopeId?: string },
+  ): Promise<OAuth2ResolvedConnection> {
+    this.logDebug('Resolving social connection', { providerRef, scopeId: options?.scopeId });
+
+    // 1. Look up provider definition
+    const provider = AllProviders_Map[providerRef];
+    if (!provider) {
+      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+        customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+        context: { message: `OAuth2 provider '${providerRef}' not found in connector catalog` },
+      });
+    }
+
+    // 2. Find SSO_OAUTH2 protocol
+    const ssoProtocol = provider.protocols.find(
+      (p) => p.kind === ExternalProvider_ExchangeProtocol_Kind.SSO_OAUTH2,
+    );
+    if (!ssoProtocol) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: `Provider '${providerRef}' does not support SSO_OAUTH2 protocol` },
+      });
+    }
+
+    const config = ssoProtocol.defaultConfiguration as Record<string, any>;
+    const oauth2Def = config?.oauth2Definition;
+    if (!oauth2Def) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: `Provider '${providerRef}' SSO_OAUTH2 protocol has no oauth2Definition` },
+      });
+    }
+
+    // 3. Read app-specific SSO config
+    const appConfig = this.appConfigService.config;
+    const ssoProviderConfig = appConfig.auth?.ssoProviders?.[providerRef];
+    if (!ssoProviderConfig || !ssoProviderConfig.enabled) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: `SSO provider '${providerRef}' is not enabled in app configuration` },
+      });
+    }
+
+    // 4. Read OAuth2 credentials from externalProvidersConfigurations
+    const providerConfigs = appConfig.externalProvidersConfigurations?.[providerRef];
+    const protocolConfig = providerConfigs?.[ExternalProvider_ExchangeProtocol_Kind.SSO_OAUTH2] as Record<string, any> | undefined;
+
+    let clientId = protocolConfig?.authConfig?.clientId
+      || protocolConfig?.clientId
+      || oauth2Def?.clientId;
+
+    if (!clientId) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: `Missing clientId for OAuth2 provider '${providerRef}'` },
+      });
+    }
+
+    // 5. Resolve clientSecret from env-provided provider secret material
+    const secretRef = protocolConfig?.authConfig?.secretRef || config?.authConfig?.secretRef;
+    let clientSecret = '';
+
+    if (secretRef) {
+      clientSecret = this.externalProvidersRegistry.getProviderSecret(
+        providerRef,
+        ExternalProvider_ExchangeProtocol_Kind.SSO_OAUTH2,
+        secretRef,
+      ) || '';
+    }
+
+    if (!clientSecret) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: `Missing env-provided clientSecret for OAuth2 provider '${providerRef}'. Check env secretRef '${secretRef}'.` },
+      });
+    }
+
+    // 5b. Scope-level social credential overrides (P3).
+    // An org/app can override the platform-level clientId + clientSecret with their own
+    // OAuth2 app credentials (stored in SsoConfig.socialCredentialOverrides).
+    //
+    // MUST run BEFORE step 5c (signed-JWT generation). For providers like Apple, the
+    // override's clientSecret is a raw private key that still needs JWT signing.
+    // signedJwtKeyId/signedJwtTeamId are captured here and consumed in step 5c.
+    let overrideSignedJwtKeyId: string | undefined;
+    let overrideSignedJwtTeamId: string | undefined;
+    if (options?.scopeId && options.ec) {
+      const scopeType = options.scopeType || AuthScopeType.ORGANIZATION;
+      try {
+        const ssoConfig = await this.orgConfigService.loadSSOConfig(options.ec, scopeType, options.scopeId);
+        const overrides = ssoConfig?.socialCredentialOverrides;
+        const override = overrides?.find(o => o.providerRef === providerRef);
+        if (override) {
+          clientId = override.clientId;
+          clientSecret = override.clientSecret;
+          overrideSignedJwtKeyId = override.signedJwtKeyId;
+          overrideSignedJwtTeamId = override.signedJwtTeamId;
+          this.logDebug('Social credentials overridden by scope config', {
+            providerRef, scopeType, scopeId: options.scopeId,
+          });
+        }
+      } catch (err) {
+        if (!isWildoBackendError(err)) throw err;
+        this.logDebug('Scope SSO config not found for credential override (non-fatal)', {
+          providerRef, scopeType, scopeId: options.scopeId,
+        });
+      }
+    }
+
+    // 5c. Signed JWT client secret generation (extensions-driven, generic).
+    // Some providers (e.g. Apple) don't accept a static client secret — they require a
+    // short-lived JWT signed with a private key. The provider's extensions declare this
+    // via clientSecretType='signed_jwt'.
+    //
+    // At this point, `clientSecret` holds either the app-level or overridden private key
+    // (determined by step 5b). The JWT params (teamId, keyId) are resolved with a
+    // fallback chain: override values from step 5b → app-level secrets store.
+    // Protocol constants (algorithm, audience, lifetime) always come from extensions.
+    const extensions = oauth2Def.extensions || {};
+    if (extensions.clientSecretType === 'signed_jwt') {
+      const algorithm = extensions.clientSecretAlgorithm as string;
+      const audience = extensions.clientSecretAudience as string;
+      const maxLifetimeSeconds = extensions.clientSecretMaxLifetimeSeconds as number;
+
+      if (!algorithm || !audience || !maxLifetimeSeconds) {
+        throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+          context: { message: `Provider '${providerRef}' has clientSecretType='signed_jwt' but missing required extensions: clientSecretAlgorithm, clientSecretAudience, clientSecretMaxLifetimeSeconds` },
+        });
+      }
+
+      const teamIdRef = (extensions.teamIdSecretRef as string) || `${providerRef.toUpperCase()}_TEAM_ID`;
+      const keyIdRef = (extensions.keyIdSecretRef as string) || `${providerRef.toUpperCase()}_KEY_ID`;
+      const teamId = overrideSignedJwtTeamId || this.externalProvidersRegistry.getProviderSecret(
+        providerRef,
+        ExternalProvider_ExchangeProtocol_Kind.SSO_OAUTH2,
+        teamIdRef,
+      );
+      const keyId = overrideSignedJwtKeyId || this.externalProvidersRegistry.getProviderSecret(
+        providerRef,
+        ExternalProvider_ExchangeProtocol_Kind.SSO_OAUTH2,
+        keyIdRef,
+      );
+
+      if (!teamId || !keyId) {
+        const missing = [!teamId ? teamIdRef : '', !keyId ? keyIdRef : ''].filter(Boolean).join(', ');
+        throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+          context: { message: `Provider '${providerRef}' requires signed JWT client secret. Missing secrets: ${missing}` },
+        });
+      }
+
+      clientSecret = getOrGenerateSignedJwtClientSecret(
+        providerRef,
+        clientId,
+        { privateKey: clientSecret, keyId, teamId, clientId, algorithm, audience, maxLifetimeSeconds },
+      );
+      this.logDebug('Generated signed JWT client secret', { providerRef, algorithm, audience });
+    }
+
+    // 6. Derive redirectUri from publicUrl (TRAP 14: publicUrl is optional)
+    const publicUrl = appConfig.runtime?.endPoints?.main_backend_api?.publicUrl;
+    if (!publicUrl) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: 'runtime.endPoints.main_backend_api.publicUrl is required for OAuth2 redirect URI derivation' },
+      });
+    }
+    const redirectUri = `${publicUrl}/api/v1/auth/oauth2/callback/${providerRef}`;
+
+    // 7. Build the resolved connection
+    const endpoints = oauth2Def.endpoints || {};
+    const capabilities = oauth2Def.capabilities || {};
+    const tokenConfig = oauth2Def.tokenConfig || {};
+
+    // Token endpoint auth method
+    const tokenEndpointAuthMethod = this.resolveTokenEndpointAuthMethod(tokenConfig.tokenEndpointAuthMethod);
+
+    // Response mode (from extraAuthParams or default 'query')
+    const responseMode = this.resolveResponseMode(oauth2Def.extraAuthParams);
+
+    // Identity source
+    const identitySource = this.resolveIdentitySource(extensions, endpoints.userInfoUrl);
+
+    // PKCE method
+    const pkceMethod = this.resolvePKCEMethod(capabilities);
+
+    // Scopes: provider defaults + app-specific additional scopes
+    const defaultScopes = oauth2Def.scopes?.defaultForSSO || [];
+    const additionalScopes = ssoProviderConfig.additionalScopes || [];
+    const scopes = [...new Set([...defaultScopes, ...additionalScopes])];
+
+    // Profile mapping
+    const profileMapping = this.buildProfileMapping(oauth2Def.userProfileMapping, extensions);
+
+    // Extra parameters
+    const extraAuthParams = { ...(oauth2Def.extraAuthParams || {}) };
+    const extraTokenParams = { ...(oauth2Def.extraTokenParams || {}) };
+    const tokenRequestHeaders = { ...(tokenConfig.tokenRequestHeaders || {}) };
+
+    // Issuer and JWKS for ID token validation
+    const issuer = extensions.issuer as string | undefined
+      || (endpoints.discoveryUrl ? endpoints.discoveryUrl.replace('/.well-known/openid-configuration', '') : undefined);
+    const jwksUri = endpoints.jwksUrl;
+
+    const connection: OAuth2ResolvedConnection = {
+      source: SsoProtocol.OIDC,
+      connectionType: 'social',
+      providerRef,
+      displayName: ssoProviderConfig.displayName || oauth2Def.displayName || provider.displayName,
+      authorizationUrl: endpoints.authorizationUrl,
+      tokenUrl: endpoints.tokenUrl,
+      userInfoUrl: endpoints.userInfoUrl,
+      redirectUri,
+      issuer,
+      jwksUri,
+      clientId,
+      clientSecret,
+      tokenEndpointAuthMethod,
+      scopes,
+      pkceMethod,
+      responseMode,
+      identitySource,
+      profileMapping,
+      extraAuthParams: Object.keys(extraAuthParams).length > 0 ? extraAuthParams : undefined,
+      extraTokenParams: Object.keys(extraTokenParams).length > 0 ? extraTokenParams : undefined,
+      tokenRequestHeaders: Object.keys(tokenRequestHeaders).length > 0 ? tokenRequestHeaders : undefined,
+      extensions: Object.keys(extensions).length > 0 ? extensions : undefined,
+    };
+
+    this.logDebug('Social connection resolved', {
+      providerRef,
+      connectionType: 'social',
+      responseMode,
+      identitySource,
+      pkceMethod,
+      scopeCount: scopes.length,
+    });
+
+    return connection;
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Enterprise Connection Resolution (Step 15)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Resolve an enterprise SSO connection from scope-level OIDC configuration.
+   *
+   * Branches on `templateMode`:
+   * - **template**: Load provider definition from AllProviders_Map[externalProviderId],
+   *   extract SSO_OAUTH2 protocol, apply templateOverrides to URLs
+   * - **discovery**: Call OIDCDiscoveryService.discoverEndpoints(issuer)
+   * - **manual**: Use provided endpoints directly
+   *
+   * The result is an OAuth2ResolvedConnection with connectionType: 'enterprise'.
+   * The OAuth2 engine (buildAuthorizationUrl, handleCallback, fetchUserProfile) is
+   * reused unchanged — only the resolver logic is different.
+   */
+  public async resolveEnterpriseConnection(
+    ec: ExecutionContext<any>,
+    scopeType: AuthScopeType,
+    scopeId: string,
+    connectionId: string,
+  ): Promise<OAuth2ResolvedConnection> {
+    this.logDebug('Resolving enterprise connection', { scopeType, scopeId, connectionId });
+
+    // 1. Load the SsoConnection resource by connectionId
+    const connResourceType = scopeType === AuthScopeType.ORGANIZATION
+      ? CoreResourceType.ORGANIZATION_SSO_CONNECTIONS
+      : CoreResourceType.APPLICATION_SSO_CONNECTIONS;
+
+    const scopeFilter = scopeType === AuthScopeType.ORGANIZATION
+      ? { organizationId: scopeId }
+      : { applicationId: scopeId };
+    const ssoConnection = await this.servicesRegistryHandler.read<SsoConnectionBase>(connResourceType, ec, { _id: connectionId, ...scopeFilter });
+
+    if (!ssoConnection || !ssoConnection.enabled) {
+      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+        customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+        context: { message: `SSO connection '${connectionId}' not found or disabled in ${scopeType} '${scopeId}'` },
+      });
+    }
+
+    // 2. SAML connections use a separate authentication flow — reject if this is a SAML connection
+    if (ssoConnection.protocol === SsoProtocol.SAML) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: 'SAML connections use the SAML authentication flow, not the OAuth2 resolver. Use /auth/saml/login/:connectionId instead.' },
+      });
+    }
+
+    if (!ssoConnection.oidc) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: `SSO connection '${connectionId}' has protocol 'oidc' but no OIDC configuration object.` },
+      });
+    }
+
+    // 3. Build a flattened config view for the downstream resolution methods
+    const oidcConfig: Record<string, any> = {
+      ...ssoConnection.oidc,
+      externalProviderId: ssoConnection.externalProviderId,
+      displayName: ssoConnection.displayName,
+      allowedDomains: ssoConnection.allowedDomains,
+      autoCreateUsers: ssoConnection.autoCreateUsers,
+      autoVerifyEmail: ssoConnection.autoVerifyEmail,
+      defaultRole: ssoConnection.defaultRole,
+      roleMapping: ssoConnection.roleMapping,
+      groupMapping: ssoConnection.groupMapping,
+    };
+
+    // 4. Resolve endpoints based on templateMode
+    const templateMode = oidcConfig.templateMode || 'manual';
+    let authorizationUrl: string;
+    let tokenUrl: string;
+    let userInfoUrl: string | undefined;
+    let jwksUri: string | undefined;
+    let endSessionEndpoint: string | undefined;
+    let issuer: string | undefined;
+    let scopes: string[];
+    let extraAuthParams: Record<string, string> | undefined;
+    let pkceMethod: 'S256' | 'plain' | null = oidcConfig.pkceEnabled ? (oidcConfig.pkceMethod === 'plain' ? 'plain' : 'S256') : null;
+
+    switch (templateMode) {
+      case 'template':
+        ({ authorizationUrl, tokenUrl, userInfoUrl, jwksUri, endSessionEndpoint, issuer, scopes, extraAuthParams, pkceMethod } =
+          await this.resolveFromTemplate(oidcConfig, pkceMethod));
+        break;
+
+      case 'discovery':
+        ({ authorizationUrl, tokenUrl, userInfoUrl, jwksUri, endSessionEndpoint, issuer, scopes } =
+          await this.resolveFromDiscovery(oidcConfig));
+        break;
+
+      case 'manual':
+      default:
+        ({ authorizationUrl, tokenUrl, userInfoUrl, jwksUri, endSessionEndpoint, issuer, scopes } =
+          this.resolveFromManual(oidcConfig));
+        break;
+    }
+
+    // 4. Derive redirectUri from publicUrl
+    const publicUrl = this.appConfigService.config.runtime?.endPoints?.main_backend_api?.publicUrl;
+    if (!publicUrl) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: 'runtime.endPoints.main_backend_api.publicUrl is required for OAuth2 redirect URI derivation' },
+      });
+    }
+    const providerRef = oidcConfig.externalProviderId || 'enterprise-oidc';
+    const redirectUri = `${publicUrl}/api/v1/auth/oauth2/callback/${providerRef}`;
+
+    // 5. Map org claimsMapping → canonical profileMapping
+    const profileMapping = this.buildEnterpriseProfileMapping(oidcConfig.claimsMapping);
+
+    // 6. Build response mode
+    const responseMode = oidcConfig.responseMode || 'query';
+
+    // 7. Assemble OAuth2ResolvedConnection
+    const connection: OAuth2ResolvedConnection = {
+      source: SsoProtocol.OIDC,
+      connectionType: 'enterprise',
+      providerRef,
+      displayName: oidcConfig.displayName,
+      authorizationUrl,
+      tokenUrl,
+      userInfoUrl,
+      redirectUri,
+      issuer,
+      jwksUri,
+      clientId: oidcConfig.clientId,
+      clientSecret: oidcConfig.clientSecret,
+      tokenEndpointAuthMethod: 'client_secret_post',
+      scopes,
+      pkceMethod,
+      responseMode: responseMode as 'query' | 'fragment' | 'form_post',
+      identitySource: userInfoUrl ? 'userinfo' : 'id_token',
+      profileMapping,
+      extraAuthParams,
+      organization: {
+        organizationId: scopeId,
+        scopeType,
+        scopeId,
+        connectionId,
+        allowedDomains: oidcConfig.allowedDomains,
+        autoCreateUsers: oidcConfig.autoCreateUsers,
+        autoVerifyEmail: oidcConfig.autoVerifyEmail,
+        defaultRole: oidcConfig.defaultRole,
+        roleMapping: oidcConfig.roleMapping,
+        groupMapping: oidcConfig.groupMapping,
+      },
+    };
+
+    this.logDebug('Enterprise connection resolved', {
+      scopeType,
+      scopeId,
+      connectionId,
+      templateMode,
+      providerRef,
+      hasUserInfoUrl: !!userInfoUrl,
+    });
+
+    return connection;
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Enterprise Resolution Strategies
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Template mode: Load provider definition from AllProviders_Map and apply org overrides.
+   * Example: Microsoft Azure AD — load Microsoft provider template, substitute {tenant} in URLs.
+   */
+  private async resolveFromTemplate(
+    oidcConfig: Record<string, any>,
+    defaultPkceMethod: 'S256' | 'plain' | null,
+  ): Promise<{
+    authorizationUrl: string; tokenUrl: string; userInfoUrl?: string;
+    jwksUri?: string; endSessionEndpoint?: string; issuer?: string;
+    scopes: string[]; extraAuthParams?: Record<string, string>;
+    pkceMethod: 'S256' | 'plain' | null;
+  }> {
+    const externalProviderId = oidcConfig.externalProviderId;
+    if (!externalProviderId) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: 'templateMode=template requires externalProviderId' },
+      });
+    }
+
+    const provider = AllProviders_Map[externalProviderId];
+    if (!provider) {
+      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+        customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+        context: { message: `Provider '${externalProviderId}' not found in connector catalog` },
+      });
+    }
+
+    const ssoProtocol = provider.protocols.find(
+      p => p.kind === ExternalProvider_ExchangeProtocol_Kind.SSO_OAUTH2,
+    );
+    if (!ssoProtocol) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: `Provider '${externalProviderId}' does not support SSO_OAUTH2 protocol` },
+      });
+    }
+
+    const config = ssoProtocol.defaultConfiguration as Record<string, any>;
+    const oauth2Def = config?.oauth2Definition;
+    if (!oauth2Def) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: `Provider '${externalProviderId}' SSO_OAUTH2 protocol has no oauth2Definition` },
+      });
+    }
+
+    const endpoints = oauth2Def.endpoints || {};
+    const capabilities = oauth2Def.capabilities || {};
+    const templateOverrides = oidcConfig.templateOverrides || {};
+
+    // Apply template variable substitution to endpoint URLs
+    const authorizationUrl = this.oidcDiscovery.resolveTemplateUrl(endpoints.authorizationUrl || '', templateOverrides);
+    const tokenUrl = this.oidcDiscovery.resolveTemplateUrl(endpoints.tokenUrl || '', templateOverrides);
+    const userInfoUrl = endpoints.userInfoUrl
+      ? this.oidcDiscovery.resolveTemplateUrl(endpoints.userInfoUrl, templateOverrides)
+      : undefined;
+    const jwksUri = endpoints.jwksUrl
+      ? this.oidcDiscovery.resolveTemplateUrl(endpoints.jwksUrl, templateOverrides)
+      : undefined;
+    const discoveryUrlTemplate = endpoints.discoveryUrl;
+    const endSessionEndpoint = undefined; // Discovery would need to be fetched for this
+
+    // Resolve issuer from discovery URL template
+    const issuer = discoveryUrlTemplate
+      ? this.oidcDiscovery.resolveTemplateUrl(
+          discoveryUrlTemplate.replace('/.well-known/openid-configuration', ''),
+          templateOverrides,
+        )
+      : undefined;
+
+    // Scopes: template defaults + org custom scopes
+    const defaultScopes = oauth2Def.scopes?.defaultForSSO || ['openid', 'email', 'profile'];
+    const customScopes = oidcConfig.customScopes || [];
+    const scopes = [...new Set([...defaultScopes, ...oidcConfig.scopes, ...customScopes])];
+
+    // Extra auth params from template + overrides
+    let extraAuthParams: Record<string, string> | undefined;
+    if (oauth2Def.extraAuthParams) {
+      extraAuthParams = this.oidcDiscovery.resolveTemplateParams(oauth2Def.extraAuthParams, templateOverrides);
+    }
+
+    // PKCE from template capabilities
+    const pkceMethod = capabilities.supportsPKCE ? (capabilities.preferredPKCEMethod === 'plain' ? 'plain' as const : 'S256' as const) : defaultPkceMethod;
+
+    return { authorizationUrl, tokenUrl, userInfoUrl, jwksUri, endSessionEndpoint, issuer, scopes, extraAuthParams, pkceMethod };
+  }
+
+  /**
+   * Discovery mode: Auto-discover endpoints from .well-known/openid-configuration.
+   * Used for Okta, Auth0, and generic OIDC providers.
+   */
+  private async resolveFromDiscovery(
+    oidcConfig: Record<string, any>,
+  ): Promise<{
+    authorizationUrl: string; tokenUrl: string; userInfoUrl?: string;
+    jwksUri?: string; endSessionEndpoint?: string; issuer?: string;
+    scopes: string[];
+  }> {
+    const issuerUrl = oidcConfig.issuer || oidcConfig.discoveryUrl?.replace('/.well-known/openid-configuration', '');
+    if (!issuerUrl) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: 'templateMode=discovery requires issuer or discoveryUrl' },
+      });
+    }
+
+    const doc = await this.oidcDiscovery.discoverEndpoints(issuerUrl);
+
+    const customScopes = oidcConfig.customScopes || [];
+    const scopes = [...new Set([...oidcConfig.scopes, ...customScopes])];
+
+    return {
+      authorizationUrl: doc.authorization_endpoint,
+      tokenUrl: doc.token_endpoint,
+      userInfoUrl: doc.userinfo_endpoint,
+      jwksUri: doc.jwks_uri,
+      endSessionEndpoint: doc.end_session_endpoint,
+      issuer: doc.issuer,
+      scopes,
+    };
+  }
+
+  /**
+   * Manual mode: Use all provided endpoints directly (backward-compatible).
+   */
+  private resolveFromManual(
+    oidcConfig: Record<string, any>,
+  ): {
+    authorizationUrl: string; tokenUrl: string; userInfoUrl?: string;
+    jwksUri?: string; endSessionEndpoint?: string; issuer?: string;
+    scopes: string[];
+  } {
+    if (!oidcConfig.authorizationEndpoint || !oidcConfig.tokenEndpoint) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: 'templateMode=manual requires authorizationEndpoint and tokenEndpoint' },
+      });
+    }
+
+    const customScopes = oidcConfig.customScopes || [];
+    const scopes = [...new Set([...oidcConfig.scopes, ...customScopes])];
+
+    return {
+      authorizationUrl: oidcConfig.authorizationEndpoint,
+      tokenUrl: oidcConfig.tokenEndpoint,
+      userInfoUrl: oidcConfig.userInfoEndpoint,
+      jwksUri: oidcConfig.jwksUri,
+      endSessionEndpoint: oidcConfig.endSessionEndpoint,
+      issuer: oidcConfig.issuer,
+      scopes,
+    };
+  }
+
+  /**
+   * Build profile mapping from org OIDC claimsMapping.
+   */
+  private buildEnterpriseProfileMapping(claimsMapping: Record<string, any>): OAuth2ProfileMapping {
+    const m = claimsMapping || {};
+    return {
+      id: 'sub',
+      email: m.email,
+      firstName: m.firstName,
+      lastName: m.lastName,
+      name: 'name',
+      image: 'picture',
+      emailVerified: 'email_verified',
+      roles: m.roles,
+      groups: m.groups,
+      department: m.department,
+      employeeId: m.employeeId,
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // G3: Org-Level OAuth2 Provider Restrictions
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Check if a specific OAuth2 social provider is allowed for a scope (org or app).
+   *
+   * Evaluation order:
+   * 1. No config / no restrictions → allowed (backward-compatible)
+   * 2. requireEnterpriseSSOOnly → blocked (all social providers)
+   * 3. allowedProviders non-empty and provider not in list → blocked
+   * 4. blockedProviders includes provider → blocked (takes precedence over allowlist)
+   * 5. Otherwise → allowed
+   */
+  public async isProviderAllowed(
+    ec: ExecutionContext<any>,
+    scopeType: AuthScopeType,
+    scopeId: string,
+    providerRef: string,
+  ): Promise<{ allowed: boolean; reason?: string }> {
+    const ssoConfig = await this.orgConfigService.loadSSOConfig(ec, scopeType, scopeId);
+    if (!(ssoConfig as any)?.oauth2ProviderRestrictions) {
+      return { allowed: true };
+    }
+
+    const restrictions = (ssoConfig as any).oauth2ProviderRestrictions;
+
+    // D6: requireEnterpriseSSOOnly (legacy: requireOrganizationSSOOnly)
+    if (restrictions.requireEnterpriseSSOOnly || restrictions.requireOrganizationSSOOnly) {
+      return { allowed: false, reason: 'Organization requires enterprise SSO only' };
+    }
+
+    if (restrictions.allowedProviders?.length > 0 && !restrictions.allowedProviders.includes(providerRef)) {
+      return { allowed: false, reason: 'Provider not in organization allowlist' };
+    }
+
+    if (restrictions.blockedProviders?.includes(providerRef)) {
+      return { allowed: false, reason: 'Provider blocked by organization policy' };
+    }
+
+    return { allowed: true };
+  }
+
+  /**
+   * Filter a list of OAuth2 social provider refs by scope-level restrictions.
+   * Returns only the providers that are allowed for the scope.
+   */
+  public async filterProviders(
+    ec: ExecutionContext<any>,
+    scopeType: AuthScopeType,
+    scopeId: string,
+    providerRefs: string[],
+  ): Promise<string[]> {
+    const results = await Promise.all(
+      providerRefs.map(async (ref) => {
+        const { allowed } = await this.isProviderAllowed(ec, scopeType, scopeId, ref);
+        return allowed ? ref : null;
+      }),
+    );
+    return results.filter((ref): ref is string => ref !== null);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // State-Based Resolution (Callback Router)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Re-resolve a connection from state token metadata on OAuth2 callback.
+   *
+   * The callback handler calls this to get fresh credentials matching the
+   * authorize-time configuration. Dispatches to resolveSocialConnection()
+   * or resolveEnterpriseConnection() based on connectionType in the token.
+   *
+   * For social connections with a scopeId, the scope context is forwarded
+   * to resolveSocialConnection() so it can apply credential overrides (P3)
+   * and signed-JWT generation in the correct order.
+   *
+   * Backward compatibility: state tokens issued before the scopeType/scopeId
+   * migration carry `organizationId` instead. The fallback chain ensures
+   * those in-flight tokens still resolve correctly during rollout.
+   */
+  public async resolveFromState(
+    ec: ExecutionContext<any>,
+    stateMetadata: OAuth2StateTokenMetadata,
+  ): Promise<OAuth2ResolvedConnection> {
+    // Backward compat: pre-migration tokens have organizationId, not scopeId
+    const scopeId = stateMetadata.scopeId || stateMetadata.organizationId;
+    const scopeType = stateMetadata.scopeType || (scopeId ? AuthScopeType.ORGANIZATION : undefined);
+
+    if (stateMetadata.connectionType === 'enterprise') {
+      if (!scopeId || !stateMetadata.connectionId) {
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.VALIDATION,
+          context: { message: 'Enterprise state token missing scopeId/organizationId or connectionId' },
+        });
+      }
+      return this.resolveEnterpriseConnection(
+        ec,
+        scopeType || AuthScopeType.ORGANIZATION,
+        scopeId,
+        stateMetadata.connectionId,
+      );
+    }
+
+    return this.resolveSocialConnection(stateMetadata.providerRef, scopeId ? {
+      ec,
+      scopeType: scopeType || AuthScopeType.ORGANIZATION,
+      scopeId,
+    } : undefined);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Private Helpers
+  // ═══════════════════════════════════════════════════════════════
+
+  private resolveTokenEndpointAuthMethod(
+    method?: string,
+  ): 'client_secret_post' | 'client_secret_basic' | 'none' {
+    switch (method) {
+      case 'client_secret_basic':
+        return 'client_secret_basic';
+      case 'none':
+        return 'none';
+      default:
+        return 'client_secret_post';
+    }
+  }
+
+  private resolveResponseMode(
+    extraAuthParams?: Record<string, string>,
+  ): 'query' | 'fragment' | 'form_post' {
+    const mode = extraAuthParams?.response_mode;
+    if (mode === 'form_post') return 'form_post';
+    if (mode === 'fragment') return 'fragment';
+    return 'query';
+  }
+
+  private resolveIdentitySource(
+    extensions: Record<string, unknown>,
+    userInfoUrl?: string,
+  ): 'userinfo' | 'id_token' | 'callback_body' {
+    if (extensions.identitySource === 'id_token') return 'id_token';
+    if (extensions.identitySource === 'callback_body') return 'callback_body';
+    if (userInfoUrl) return 'userinfo';
+    return 'id_token'; // Fallback for providers without userinfo
+  }
+
+  private resolvePKCEMethod(
+    capabilities: Record<string, unknown>,
+  ): 'S256' | 'plain' | null {
+    if (!capabilities.supportsPKCE) return null;
+    const preferred = capabilities.preferredPKCEMethod as string | undefined;
+    if (preferred === 'plain') return 'plain';
+    return 'S256'; // Default to S256 when PKCE is supported
+  }
+
+  private buildProfileMapping(
+    userProfileMapping?: Record<string, string>,
+    extensions?: Record<string, unknown>,
+  ): OAuth2ProfileMapping {
+    const mapping = userProfileMapping || {};
+    return {
+      id: mapping.id || 'sub',
+      email: mapping.email || 'email',
+      name: mapping.name || 'name',
+      image: mapping.image || 'picture',
+      emailVerified: mapping.emailVerified || 'email_verified',
+      // Extension-based fields (Google provides given_name/family_name separately)
+      firstName: extensions?.firstNameField as string | undefined,
+      lastName: extensions?.lastNameField as string | undefined,
+    };
+  }
+
+}