feat(ui): wire the Security page navigation into the ConfigureSSO wizard

.changeset/whole-parents-care.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+The Security page's SSO wizard now has a back-to-Security control, and Start/Edit open the wizard at the first step (Continue resumes where you left off).

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

@@ -25,6 +25,7 @@ export interface ConfigureSSOData {
   organizationEnterpriseConnection: OrganizationEnterpriseConnection;
   testRuns: TestRunsView;
   organizationDomains: OrganizationDomainResource[] | undefined;
+  onExit?: () => void;
 }
 
 interface ConfigureSSOProviderProps {
@@ -35,6 +36,7 @@ interface ConfigureSSOProviderProps {
   contentRef: React.RefObject<HTMLDivElement>;
   enterpriseConnectionMutations: EnterpriseConnectionMutations;
   organizationDomainMutations: OrganizationDomainMutations;
+  onExit?: () => void;
 }
 
 const ConfigureSSOContext = React.createContext<ConfigureSSOData | null>(null);
@@ -48,6 +50,7 @@ export const ConfigureSSOProvider = ({
   contentRef,
   enterpriseConnectionMutations,
   organizationDomainMutations,
+  onExit,
   children,
 }: PropsWithChildren<ConfigureSSOProviderProps>): JSX.Element => {
   const value = React.useMemo<ConfigureSSOData>(
@@ -59,6 +62,7 @@ export const ConfigureSSOProvider = ({
       organizationDomains,
       enterpriseConnectionMutations,
       organizationDomainMutations,
+      onExit,
     }),
     [
       contentRef,
@@ -68,6 +72,7 @@ export const ConfigureSSOProvider = ({
       testRuns,
       organizationDomains,
       enterpriseConnection,
+      onExit,
     ],
   );
 

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

@@ -1,23 +1,14 @@
-import { useLocalizations } from '@/customizables';
+import { Flex, useLocalizations } from '@/customizables';
 
 import { ProfileCardHeader } from './elements/ProfileCard';
 import { Stepper } from './elements/Stepper';
 import { useWizard } from './elements/Wizard';
 
-/**
- * The wizard breadcrumb, driven entirely by the generic entry-guard wizard
- * facade.
- *
- * Breadcrumb membership is the labelled steps in declaration order — the
- * provider-selection step carries no `label`, so it never appears (it replaced
- * the old `hidden` provider step). Each item's reachability comes straight from
- * the guard-driven `isReachable` flag (the same predicate `goToStep` checks), so
- * a disabled breadcrumb item and a blocked jump always agree. Completion stays
- * positional. The reset affordance now lives in the step footers
- * (`Step.Footer.Reset`), which delete the connection via the context mutation
- * rather than a wizard binding.
- */
-export const ConfigureSSOHeader = (): JSX.Element => {
+type ConfigureSSOHeaderProps = {
+  title?: React.ReactNode;
+};
+
+export const ConfigureSSOHeader = ({ title }: ConfigureSSOHeaderProps): JSX.Element => {
   const { activeSteps, currentIndex, goToStep } = useWizard();
   const { t } = useLocalizations();
 
@@ -28,27 +19,31 @@ export const ConfigureSSOHeader = (): JSX.Element => {
 
   return (
     <ProfileCardHeader>
-      <Stepper>
-        {visibleSteps.map((step, index) => {
-          const isCurrent = index === currentVisibleIndex;
-          const labelText = step.label ? (typeof step.label === 'string' ? step.label : t(step.label)) : '';
+      {title}
+
+      <Flex sx={title ? { marginInlineStart: 'auto' } : undefined}>
+        <Stepper>
+          {visibleSteps.map((step, index) => {
+            const isCurrent = index === currentVisibleIndex;
+            const labelText = step.label ? (typeof step.label === 'string' ? step.label : t(step.label)) : '';
 
-          return (
-            <Stepper.Item
-              key={step.id}
-              bullet={index + 1}
-              isCurrent={isCurrent}
-              isCompleted={step.isCompleted}
-              // Guard-driven: bind directly to the wizard's reachability flag so
-              // a disabled breadcrumb item and a blocked `goToStep` agree.
-              isReachable={step.isReachable}
-              onClick={() => goToStep(step.id)}
-            >
-              {labelText}
-            </Stepper.Item>
-          );
-        })}
-      </Stepper>
+            return (
+              <Stepper.Item
+                key={step.id}
+                bullet={index + 1}
+                isCurrent={isCurrent}
+                isCompleted={step.isCompleted}
+                // Guard-driven: bind directly to the wizard's reachability flag so
+                // a disabled breadcrumb item and a blocked `goToStep` agree.
+                isReachable={step.isReachable}
+                onClick={() => goToStep(step.id)}
+              >
+                {labelText}
+              </Stepper.Item>
+            );
+          })}
+        </Stepper>
+      </Flex>
     </ProfileCardHeader>
   );
 };

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

@@ -14,10 +14,12 @@ import {
   TestConfigurationStep,
 } from './steps';
 
-export type ConfigureSSOWizardProps = Omit<ComponentProps<typeof ConfigureSSOProvider>, 'children'>;
+export type ConfigureSSOWizardProps = Omit<ComponentProps<typeof ConfigureSSOProvider>, 'children'> & {
+  title?: React.ReactNode;
+  forceInitialStep?: boolean;
+};
 
-/** Pure, data-injected ConfigureSSO flow — hosts own fetching, loading, and permission gating. */
-export const ConfigureSSOWizard = (props: ConfigureSSOWizardProps): JSX.Element => {
+export const ConfigureSSOWizard = ({ title, forceInitialStep, ...props }: ConfigureSSOWizardProps): JSX.Element => {
   const { organizationEnterpriseConnection: c, organizationDomains } = props;
 
   const allDomainsVerified = areAllOrganizationDomainsVerified(organizationDomains);
@@ -33,11 +35,15 @@ export const ConfigureSSOWizard = (props: ConfigureSSOWizardProps): JSX.Element
     [c, allDomainsVerified],
   );
 
-  // Each step owns a `CardStateProvider` so card errors stay scoped to their step and clear when it unmounts.
+  const initialStepId = forceInitialStep ? steps[0].id : undefined;
+
   return (
     <ConfigureSSOProvider {...props}>
-      <Wizard steps={steps}>
-        <ConfigureSSOHeader />
+      <Wizard
+        steps={steps}
+        initialStepId={initialStepId}
+      >
+        <ConfigureSSOHeader title={title} />
 
         <Wizard.Match id='verify-domain'>
           <CardStateProvider>

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

@@ -71,6 +71,31 @@ describe('ConfigureSSO', () => {
     });
   });
 
+  describe('standalone mount header', () => {
+    it('renders the stepper without a back control (no host title / onExit)', async () => {
+      const { wrapper, fixtures } = await createFixtures(f => {
+        f.withEnterpriseSso({ selfServeSSO: true });
+        f.withEmailAddress();
+        f.withOrganizations();
+        f.withUser({
+          email_addresses: ['test@clerk.com'],
+          organization_memberships: [{ name: 'Org1', permissions: ['org:sys_entconns:manage'] }],
+        });
+      });
+
+      fixtures.clerk.organization?.getEnterpriseConnections.mockResolvedValue([]);
+      mockOrganizationDomains(fixtures, [verifiedDomain]);
+
+      const { findByText, queryByRole } = render(<ConfigureSSO />, { wrapper });
+
+      await findByText(/select your identity provider/i);
+
+      // The standalone wizard is mounted without `title`/`onExit`, so the header
+      // exposes no "Security" back control.
+      expect(queryByRole('button', { name: 'Security' })).not.toBeInTheDocument();
+    });
+  });
+
   describe('in a personal workspace', () => {
     it('renders the wizard without checking the manage enterprise connections permission', async () => {
       const { wrapper, fixtures } = await createFixtures(f => {

packages/ui/src/components/OrganizationProfile/OrganizationSecurityPage.tsx

@@ -1,11 +1,11 @@
 import { useOrganization } from '@clerk/shared/react';
-import { useState } from 'react';
+import React, { useState } from 'react';
 
 import { Header } from '@/ui/elements/Header';
 import { ProfileCard } from '@/ui/elements/ProfileCard';
 
-import React from 'react';
-import { Col, descriptors, localizationKeys } from '../../customizables';
+import { Col, descriptors, Icon, localizationKeys, SimpleButton, Text } from '../../customizables';
+import { ChevronLeft } from '../../icons';
 import { ConfigureSSOProtect } from '../ConfigureSSO/ConfigureSSO';
 import { ConfigureSSOSkeleton } from '../ConfigureSSO/ConfigureSSOSkeleton';
 import { ConfigureSSOWizard } from '../ConfigureSSO/ConfigureSSOWizard';
@@ -27,7 +27,6 @@ export const OrganizationSecurityPage = ({ contentRef }: OrganizationSecurityPag
   return <OrganizationSecurityPageContent contentRef={contentRef} />;
 };
 
-/** Separate from the page so the connection hook only runs behind the organization check. */
 const OrganizationSecurityPageContent = ({ contentRef }: OrganizationSecurityPageProps) => {
   const {
     organization,
@@ -41,12 +40,40 @@ const OrganizationSecurityPageContent = ({ contentRef }: OrganizationSecurityPag
   } = useOrganizationEnterpriseConnection();
 
   const [view, setView] = useState<'overview' | 'wizard'>('overview');
+  const [forceFirstStep, setForceFirstStep] = useState(false);
+
+  const exitWizard = () => setView('overview');
+
+  const openWizard = (forceInitialStep = false) => {
+    setForceFirstStep(forceInitialStep);
+    setView('wizard');
+  };
 
-  // Gate loading above the provider so the context never observes a loading state.
   if (isLoading) {
     return <ConfigureSSOSkeleton />;
   }
 
+  const backControl = (
+    <SimpleButton
+      elementDescriptor={descriptors.configureSSOHeaderBackButton}
+      variant='unstyled'
+      onClick={exitWizard}
+      sx={t => ({
+        gap: t.space.$1,
+        padding: 0,
+        color: t.colors.$colorMutedForeground,
+        '&:hover': { color: t.colors.$colorForeground },
+      })}
+    >
+      <Icon icon={ChevronLeft} />
+      <Text
+        as='span'
+        variant='body'
+        localizationKey={localizationKeys('organizationProfile.navbar.security')}
+      />
+    </SimpleButton>
+  );
+
   return (
     <ConfigureSSOProtect>
       {view === 'overview' ? (
@@ -73,7 +100,7 @@ const OrganizationSecurityPageContent = ({ contentRef }: OrganizationSecurityPag
                 deleteConnection={enterpriseConnectionMutations.deleteConnection}
                 organizationName={organization?.name ?? ''}
                 contentRef={contentRef}
-                onConfigure={() => setView('wizard')}
+                onConfigure={openWizard}
               />
             </Col>
           </Col>
@@ -87,6 +114,9 @@ const OrganizationSecurityPageContent = ({ contentRef }: OrganizationSecurityPag
           enterpriseConnectionMutations={enterpriseConnectionMutations}
           organizationDomainMutations={organizationDomainMutations}
           organizationDomains={organizationDomains}
+          forceInitialStep={forceFirstStep}
+          title={backControl}
+          onExit={exitWizard}
         />
       )}
     </ConfigureSSOProtect>

packages/ui/src/components/OrganizationProfile/SecuritySsoSection.tsx

@@ -28,7 +28,7 @@ type SecuritySsoSectionProps = {
   deleteConnection: EnterpriseConnectionMutations['deleteConnection'];
   organizationName: string;
   contentRef: React.RefObject<HTMLDivElement>;
-  onConfigure: () => void;
+  onConfigure: (forceInitialStep?: boolean) => void;
 };
 
 const STATUS_BADGES: Record<
@@ -95,7 +95,7 @@ export const SecuritySsoSection = (props: SecuritySsoSectionProps): JSX.Element
             'organizationProfile.securityPage.ssoSection.primaryButton__startConfiguration',
           )}
           primaryButtonId='start'
-          onConfigure={onConfigure}
+          onConfigure={() => onConfigure(true)}
         />
       )}
 
@@ -105,7 +105,7 @@ export const SecuritySsoSection = (props: SecuritySsoSectionProps): JSX.Element
             'organizationProfile.securityPage.ssoSection.primaryButton__continueConfiguration',
           )}
           primaryButtonId='continue'
-          onConfigure={onConfigure}
+          onConfigure={() => onConfigure()}
         />
       )}
 
@@ -205,7 +205,7 @@ const ConfiguredContent = (props: ConfiguredContentProps): JSX.Element => {
           actions={[
             {
               label: localizationKeys('organizationProfile.securityPage.ssoSection.menuAction__edit'),
-              onClick: onConfigure,
+              onClick: () => onConfigure(true),
             },
             isActive
               ? {