refactor(ui): drive ConfigureSSO wizard navigation with a state machine (#8715)

Author: iagodahlem

.changeset/quick-mammals-flash.md

@@ -0,0 +1,9 @@
+---
+'@clerk/ui': patch
+'@clerk/shared': patch
+'@clerk/clerk-js': patch
+---
+
+Internal refactor for self-serve SSO wizard navigation to leverage a guard-based state machine.
+
+It makes the step navigation more predictable: the step you land on (including after a reload) and which steps you can move to are derived from the connection's state, the connection reset flow lands you on the right step.

packages/clerk-js/src/core/resources/__tests__/Organization.test.ts

@@ -148,6 +148,10 @@ describe('Organization', () => {
       const conn = await organization.createEnterpriseConnection({
         provider: 'saml_okta',
         name: 'New SSO',
+        // `domains` is required by the org-scoped create endpoint; it is sent as
+        // a `domains` array on the body and serialized as repeated form fields
+        // (`domains=acme.com`) by the form serializer downstream.
+        domains: ['acme.com'],
         // Even though callers may still pass this for convenience, the SDK
         // must not include it in the body — the org URL is authoritative.
         organizationId: ORG_ID,
@@ -161,6 +165,7 @@ describe('Organization', () => {
         body: {
           provider: 'saml_okta',
           name: 'New SSO',
+          domains: ['acme.com'],
           saml_idp_entity_id: 'https://idp.example.com',
         },
       });
@@ -173,6 +178,42 @@ describe('Organization', () => {
       expect(conn.name).toBe('New SSO');
     });
 
+    it('omits domains from the create body when none are provided', async () => {
+      const enterpriseConnectionJSON = {
+        id: 'ec_new',
+        object: 'enterprise_connection' as const,
+        name: 'New SSO',
+        active: true,
+        provider: 'saml_okta',
+        logo_public_url: null,
+        domains: [],
+        organization_id: ORG_ID,
+        sync_user_attributes: true,
+        disable_additional_identifications: false,
+        allow_organization_account_linking: false,
+        custom_attributes: [],
+        oauth_config: null,
+        saml_connection: null,
+        created_at: 1234567890,
+        updated_at: 1234567890,
+      };
+
+      // @ts-ignore
+      BaseResource._fetch = vi.fn().mockReturnValue(Promise.resolve({ response: enterpriseConnectionJSON }));
+
+      const organization = createOrganization();
+
+      await organization.createEnterpriseConnection({
+        provider: 'saml_okta',
+        name: 'New SSO',
+      });
+
+      // @ts-ignore
+      const callBody = BaseResource._fetch.mock.calls[0][0].body;
+      // Backwards-compatible: an omitted (or empty) `domains` is not sent.
+      expect('domains' in callBody).toBe(false);
+    });
+
     it('updates an enterprise connection without forwarding organization_id in the body', async () => {
       const enterpriseConnectionJSON = {
         id: 'ec_123',

packages/clerk-js/src/utils/enterpriseConnection.ts

@@ -35,9 +35,17 @@ export function toEnterpriseConnectionBody(
 ): Record<string, unknown> {
   const body: Record<string, unknown> = {};
 
-  // Top-level fields. `provider` is only on Create, the rest are shared.
+  // Top-level fields. `provider` and `domains` are only on Create, the rest are shared.
   setIfDefined(body, 'provider', (params as CreateOrganizationEnterpriseConnectionParams).provider);
   setIfDefined(body, 'name', params.name);
+  // `domains` is an array of FQDN strings. The form serializer downstream emits
+  // each element as a repeated `domains` form field (e.g. `domains=a.com&domains=b.com`),
+  // matching how the backend parses repeated form params. An omitted or empty
+  // array is not sent, keeping older callers backwards-compatible.
+  const domains = (params as CreateOrganizationEnterpriseConnectionParams).domains;
+  if (domains && domains.length > 0) {
+    body.domains = domains;
+  }
   if (!options.omitOrganizationId) {
     setIfDefined(body, 'organization_id', params.organizationId);
   }

packages/shared/src/react/hooks/useOrganizationEnterpriseConnectionTestRuns.tsx

@@ -5,6 +5,7 @@ import type {
   GetEnterpriseConnectionTestRunsParams,
 } from '../../types/enterpriseConnectionTestRun';
 import { useClerkInstanceContext } from '../contexts';
+import { defineKeepPreviousDataFn } from '../query/keep-previous-data';
 import { useClerkQueryClient } from '../query/use-clerk-query-client';
 import { useClerkQuery } from '../query/useQuery';
 import { useOrganizationBase } from './base/useOrganizationBase';
@@ -33,6 +34,14 @@ export type UseOrganizationEnterpriseConnectionTestRunsParams = {
    * @default true
    */
   enabled?: boolean;
+  /**
+   * When `true`, a background refetch keeps the previously-loaded page visible
+   * (`isFetching` stays `true`, `isLoading` does not flip back to `true`) instead
+   * of clearing to a cold-load state.
+   *
+   * @default false
+   */
+  keepPreviousData?: boolean;
 };
 
 export type UseOrganizationEnterpriseConnectionTestRunsReturn = {
@@ -46,9 +55,26 @@ export type UseOrganizationEnterpriseConnectionTestRunsReturn = {
    */
   isPolling: boolean;
   /**
-   * Force a refetch and (if the list is currently empty) arm polling
+   * Force a refetch.
+   *
+   * By default this also arms polling when the list is currently empty, so a run
+   * kicked off elsewhere is picked up as it lands. Pass `{ armPolling: false }`
+   * for an entry/pagination refetch that should never arm polling merely because
+   * the list happens to be empty — polling is then armed only by an explicit
+   * `revalidate()` (or `revalidate({ armPolling: true })`) after a run is kicked
+   * off.
    */
-  revalidate: () => Promise<void>;
+  revalidate: (options?: RevalidateTestRunsOptions) => Promise<void>;
+};
+
+export type RevalidateTestRunsOptions = {
+  /**
+   * Whether to arm polling for the first record when the list is currently
+   * empty.
+   *
+   * @default true
+   */
+  armPolling?: boolean;
 };
 
 /**
@@ -64,6 +90,7 @@ function useOrganizationEnterpriseConnectionTestRuns(
     params: fetchParams = { initialPage: 1, pageSize: 10 },
     pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
     enabled = true,
+    keepPreviousData = false,
   } = params;
 
   const clerk = useClerkInstanceContext();
@@ -86,6 +113,12 @@ function useOrganizationEnterpriseConnectionTestRuns(
 
   const [shouldPoll, setShouldPoll] = useState(false);
 
+  useEffect(() => {
+    // Polling intent is scoped to the current connection — clear it when the
+    // connection changes so a reset/recreate doesn't inherit a stale armed poll.
+    setShouldPoll(false);
+  }, [enterpriseConnectionId]);
+
   const query = useClerkQuery({
     queryKey,
     queryFn: () => {
@@ -104,6 +137,7 @@ function useOrganizationEnterpriseConnectionTestRuns(
     },
     enabled: queryEnabled,
     refetchIntervalInBackground: false,
+    placeholderData: defineKeepPreviousDataFn(keepPreviousData),
   });
 
   const hasRows = (query.data?.data?.length ?? 0) > 0;
@@ -114,14 +148,21 @@ function useOrganizationEnterpriseConnectionTestRuns(
     }
   }, [shouldPoll, hasRows]);
 
-  const revalidate = useCallback(async () => {
-    // Only arm polling when there is nothing in the list yet — once any record
-    // has been seen, this is a one-shot refetch.
-    if (!hasRows) {
-      setShouldPoll(true);
-    }
-    await queryClient.invalidateQueries({ queryKey: invalidationKey });
-  }, [queryClient, invalidationKey, hasRows]);
+  const revalidate = useCallback(
+    async (options?: RevalidateTestRunsOptions) => {
+      // Arm polling only when the caller opts in (the default) AND there is
+      // nothing in the list yet. An entry/pagination refetch passes
+      // `armPolling: false` so an empty list on entry never arms polling on its
+      // own — that stays the job of an explicit refetch after a run is kicked
+      // off. Once any record has been seen, this is a one-shot refetch.
+      const armPolling = options?.armPolling ?? true;
+      if (armPolling && !hasRows) {
+        setShouldPoll(true);
+      }
+      await queryClient.invalidateQueries({ queryKey: invalidationKey });
+    },
+    [queryClient, invalidationKey, hasRows],
+  );
 
   const isPolling = queryEnabled && shouldPoll && !hasRows;
 

packages/shared/src/types/enterpriseConnection.ts

@@ -141,6 +141,8 @@ export type MeEnterpriseConnectionOidcInput = OrganizationEnterpriseConnectionOi
 export type CreateOrganizationEnterpriseConnectionParams = {
   provider: OrganizationEnterpriseConnectionProvider;
   name: string;
+  /** FQDN strings the connection authenticates. Required by the org-scoped create endpoint. */
+  domains?: string[];
   organizationId?: string | null;
   saml?: OrganizationEnterpriseConnectionSamlInput | null;
   oidc?: OrganizationEnterpriseConnectionOidcInput | null;

packages/ui/src/components/ConfigureSSO/ConfigureSSO.tsx

@@ -1,27 +1,22 @@
-import {
-  __internal_useOrganizationEnterpriseConnections,
-  __internal_useOrganizationEnterpriseConnectionTestRuns,
-  useSession,
-} from '@clerk/shared/react';
-import type { ConfigureSSOProps, EnterpriseConnectionResource } from '@clerk/shared/types';
+import { useSession } from '@clerk/shared/react';
+import type { ConfigureSSOProps } from '@clerk/shared/types';
 import React from 'react';
 
 import { useProtect } from '@/common';
 import { withCoreUserGuard } from '@/contexts';
 import { Col, Flex, Flow, Heading, Icon, localizationKeys, Text } from '@/customizables';
-import { useCardState, withCardStateProvider } from '@/elements/contexts';
+import { withCardStateProvider } from '@/elements/contexts';
 import { ProfileCard } from '@/elements/ProfileCard';
 import { ExclamationTriangle } from '@/icons';
 import { Route, Switch } from '@/router';
 
-import { ConfigureSSOProvider, useConfigureSSO } from './ConfigureSSOContext';
-import { ConfigureSSOHeader } from './ConfigureSSOHeader';
+import { ConfigureSSOProvider } from './ConfigureSSOContext';
 import { ConfigureSSONavbar } from './ConfigureSSONavbar';
 import { ConfigureSSOSkeleton } from './ConfigureSSOSkeleton';
+import { ConfigureSSOSteps } from './ConfigureSSOSteps';
 import { ProfileCardFooter, ProfileCardHeader } from './elements/ProfileCard';
 import { Step } from './elements/Step';
-import { useWizard, Wizard } from './elements/Wizard';
-import { ConfigureStep, ConfirmationStep, SelectProviderStep, TestConfigurationStep, VerifyDomainStep } from './steps';
+import { useOrganizationEnterpriseConnection } from './hooks/useOrganizationEnterpriseConnection';
 
 const ConfigureSSOInternal = () => {
   return (
@@ -51,90 +46,38 @@ const AuthenticatedContent = withCoreUserGuard(() => {
 
 export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
   const {
-    data: enterpriseConnections,
-    isLoading: isLoadingEnterpriseConnections,
-    createEnterpriseConnection,
-    updateEnterpriseConnection,
-    deleteEnterpriseConnection,
-  } = __internal_useOrganizationEnterpriseConnections({ enabled: true });
-  // Currently the self-serve SSO UI flow only supports one enterprise connection per organization
-  const enterpriseConnection = enterpriseConnections?.[0];
-
-  const { hasSuccessfulTestRun, isLoading: isLoadingTestRuns } = useHasSuccessfulTestRun(enterpriseConnection);
-
-  const isLoading = isLoadingEnterpriseConnections || isLoadingTestRuns;
+    isLoading,
+    enterpriseConnection,
+    organizationEnterpriseConnection,
+    testRuns,
+    mutations,
+    primaryEmailAddress,
+  } = useOrganizationEnterpriseConnection();
+
+  // Gate loading one level above the provider so the context never observes a
+  // loading state. The single test-run source is part of this initial fetch
+  // when a connection exists at load, so a cold landing on the test step is
+  // covered by the full skeleton here.
   if (isLoading) {
     return <ConfigureSSOSkeleton />;
   }
 
   return (
     <ConfigureSSOProtect>
       <ConfigureSSOProvider
-        hasSuccessfulTestRun={hasSuccessfulTestRun}
+        organizationEnterpriseConnection={organizationEnterpriseConnection}
+        testRuns={testRuns}
         enterpriseConnection={enterpriseConnection}
         contentRef={contentRef}
-        createEnterpriseConnection={createEnterpriseConnection}
-        updateEnterpriseConnection={updateEnterpriseConnection}
-        deleteEnterpriseConnection={deleteEnterpriseConnection}
+        mutations={mutations}
+        primaryEmailAddress={primaryEmailAddress}
       >
         <ConfigureSSOSteps />
       </ConfigureSSOProvider>
     </ConfigureSSOProtect>
   );
 };
 
-const ConfigureSSOSteps = () => {
-  const { initialStepId, enterpriseConnection } = useConfigureSSO();
-
-  return (
-    <Wizard initialStepId={initialStepId}>
-      <ResetCardErrorOnStepChange />
-      <ConfigureSSOHeader />
-
-      {/*
-       * `select-provider` is only a wizard step while there's no enterprise
-       * connection yet — creating one unregisters this step, which:
-       *   1. Hides it from the breadcrumb (no need for a manual filter), and
-       *   2. Prevents `goPrev` from any later step (e.g. configure's first
-       *      substep) from ever bubbling back into provider selection.
-       */}
-      {!enterpriseConnection && (
-        <Wizard.Step id='select-provider'>
-          <SelectProviderStep />
-        </Wizard.Step>
-      )}
-
-      <Wizard.Step
-        id='verify-domain'
-        label='Verify domain'
-      >
-        <VerifyDomainStep />
-      </Wizard.Step>
-
-      <Wizard.Step
-        id='configure'
-        label='Configure'
-      >
-        <ConfigureStep />
-      </Wizard.Step>
-
-      <Wizard.Step
-        id='test'
-        label='Test'
-      >
-        <TestConfigurationStep />
-      </Wizard.Step>
-
-      <Wizard.Step
-        id='confirmation'
-        label='Confirmation'
-      >
-        <ConfirmationStep />
-      </Wizard.Step>
-    </Wizard>
-  );
-};
-
 const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
   const { session } = useSession();
   const isPersonalWorkspace = !session?.lastActiveOrganizationId;
@@ -193,44 +136,4 @@ const MissingManageEnterpriseConnectionsPermission = () => (
   </>
 );
 
-/**
- * Sentinel component rendered inside `<Wizard>`
- *
- * Clears any card-level error whenever the active step transitions, so a stale failure from one step
- * doesn't leak into the next
- */
-const ResetCardErrorOnStepChange = (): null => {
-  const { currentStep } = useWizard();
-  const card = useCardState();
-  const previousStepIdRef = React.useRef(currentStep?.id);
-
-  React.useEffect(() => {
-    if (previousStepIdRef.current === currentStep?.id) {
-      return;
-    }
-
-    previousStepIdRef.current = currentStep?.id;
-    card.setError(undefined);
-  }, [currentStep?.id, card]);
-
-  return null;
-};
-
-/**
- * Fetches a single successful test run for the given connection on mount
- */
-const useHasSuccessfulTestRun = (
-  enterpriseConnection: EnterpriseConnectionResource | undefined,
-): { hasSuccessfulTestRun: boolean; isLoading: boolean } => {
-  const { data: successfulTestRuns, isLoading } = __internal_useOrganizationEnterpriseConnectionTestRuns({
-    enterpriseConnectionId: enterpriseConnection?.id ?? null,
-    params: { initialPage: 1, pageSize: 1, status: ['success'] },
-  });
-
-  return {
-    hasSuccessfulTestRun: (successfulTestRuns?.length ?? 0) > 0,
-    isLoading,
-  };
-};
-
 export const ConfigureSSO: React.ComponentType<ConfigureSSOProps> = withCardStateProvider(ConfigureSSOInternal);