feat(ui): <ConfigureSSO /> POC

.changeset/lucky-tables-learn.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Add wizard steps for the `<__experimental_ConfigureSSO />` component

packages/clerk-js/src/core/clerk.ts

@@ -1457,6 +1457,15 @@ export class Clerk implements ClerkInterface {
       return;
     }
 
+    if (noUserExists(this)) {
+      if (this.#instanceType === 'development') {
+        throw new ClerkRuntimeError(warnings.cannotRenderConfigureSSOComponentWhenUserDoesNotExist, {
+          code: CANNOT_RENDER_USER_MISSING_ERROR_CODE,
+        });
+      }
+      return;
+    }
+
     this.assertComponentsReady(this.#clerkUI);
     const component = 'ConfigureSSO';
     void this.#clerkUI

packages/clerk-js/src/core/resources/User.ts

@@ -43,7 +43,6 @@ import type {
   VerifyTOTPParams,
   Web3WalletResource,
 } from '@clerk/shared/types';
-import { deepCamelToSnake } from '@clerk/shared/underscore';
 
 import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
@@ -551,25 +550,64 @@ export class User extends BaseResource implements UserResource {
  * Serializes `CreateMeEnterpriseConnectionParams` / `UpdateMeEnterpriseConnectionParams`
  * for the `/me/enterprise_connections` FAPI endpoints.
  *
- * Uses `deepCamelToSnake` but preserves `saml.attributeMapping` and `customAttributes` as-is. Their keys are
+ * The handler expects a flat form body where SAML and OIDC fields are
+ * prefixed (e.g. `saml_idp_metadata_url`, `oidc_client_id`) rather
+ * than nested under `saml`/`oidc` objects. `attribute_mapping` and
+ * `custom_attributes` stay as object values and are JSON-stringified
+ * by the form serializer downstream — their inner keys are
  * user-supplied data and must not be camel→snake transformed.
  */
 function toMeEnterpriseConnectionBody(
   params: CreateMeEnterpriseConnectionParams | UpdateMeEnterpriseConnectionParams,
 ): Record<string, unknown> {
-  const originalAttributeMapping =
-    params.saml && typeof params.saml === 'object' ? params.saml.attributeMapping : undefined;
-  const originalCustomAttributes = 'customAttributes' in params ? params.customAttributes : undefined;
-
-  const body = deepCamelToSnake(params) as Record<string, any>;
-
-  if (originalAttributeMapping !== undefined && body.saml && typeof body.saml === 'object') {
-    body.saml.attribute_mapping = originalAttributeMapping;
+  const body: Record<string, unknown> = {};
+
+  // Top-level fields. `provider` is only on Create, the rest are shared
+  setIfDefined(body, 'provider', (params as CreateMeEnterpriseConnectionParams).provider);
+  setIfDefined(body, 'name', params.name);
+  setIfDefined(body, 'organization_id', params.organizationId);
+  setIfDefined(body, 'active', (params as UpdateMeEnterpriseConnectionParams).active);
+  setIfDefined(body, 'sync_user_attributes', (params as UpdateMeEnterpriseConnectionParams).syncUserAttributes);
+  setIfDefined(
+    body,
+    'disable_additional_identifications',
+    (params as UpdateMeEnterpriseConnectionParams).disableAdditionalIdentifications,
+  );
+  setIfDefined(body, 'custom_attributes', (params as UpdateMeEnterpriseConnectionParams).customAttributes);
+
+  if (params.saml) {
+    setIfDefined(body, 'saml_idp_entity_id', params.saml.idpEntityId);
+    setIfDefined(body, 'saml_idp_sso_url', params.saml.idpSsoUrl);
+    setIfDefined(body, 'saml_idp_certificate', params.saml.idpCertificate);
+    setIfDefined(body, 'saml_idp_metadata_url', params.saml.idpMetadataUrl);
+    setIfDefined(body, 'saml_idp_metadata', params.saml.idpMetadata);
+    setIfDefined(body, 'saml_attribute_mapping', params.saml.attributeMapping);
+    setIfDefined(body, 'saml_allow_subdomains', params.saml.allowSubdomains);
+    setIfDefined(body, 'saml_allow_idp_initiated', params.saml.allowIdpInitiated);
+    setIfDefined(body, 'saml_force_authn', params.saml.forceAuthn);
   }
 
-  if (originalCustomAttributes !== undefined) {
-    body.custom_attributes = originalCustomAttributes;
+  if (params.oidc) {
+    setIfDefined(body, 'oidc_client_id', params.oidc.clientId);
+    setIfDefined(body, 'oidc_client_secret', params.oidc.clientSecret);
+    setIfDefined(body, 'oidc_discovery_url', params.oidc.discoveryUrl);
+    setIfDefined(body, 'oidc_auth_url', params.oidc.authUrl);
+    setIfDefined(body, 'oidc_token_url', params.oidc.tokenUrl);
+    setIfDefined(body, 'oidc_user_info_url', params.oidc.userInfoUrl);
+    setIfDefined(body, 'oidc_requires_pkce', params.oidc.requiresPkce);
   }
 
   return body;
 }
+
+/**
+ * Adds `value` under `key` only when the caller actually provided it.
+ * Mirrors the SDK's existing semantics: `undefined` means "don't send
+ * this field"; `null` is forwarded so users can explicitly clear a
+ * value via the form-encoded body
+ */
+function setIfDefined(target: Record<string, unknown>, key: string, value: unknown): void {
+  if (value !== undefined) {
+    target[key] = value;
+  }
+}

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

@@ -184,7 +184,7 @@ describe('User', () => {
         provider: 'saml_okta',
         name: 'New SSO',
         organization_id: 'org_1',
-        saml: { idp_entity_id: 'https://idp.example.com' },
+        saml_idp_entity_id: 'https://idp.example.com',
       },
     });
 
@@ -291,13 +291,11 @@ describe('User', () => {
       body: {
         provider: 'saml_okta',
         name: 'New SSO',
-        saml: {
-          idp_entity_id: 'https://idp.example.com',
-          attribute_mapping: {
-            emailAddress: 'mail',
-            firstName: 'givenName',
-            'custom:role': 'role',
-          },
+        saml_idp_entity_id: 'https://idp.example.com',
+        saml_attribute_mapping: {
+          emailAddress: 'mail',
+          firstName: 'givenName',
+          'custom:role': 'role',
         },
       },
     });
@@ -359,11 +357,9 @@ describe('User', () => {
           CustomValue: 'y',
           nestedCamelKey: { innerCamelKey: 'z' },
         },
-        saml: {
-          attribute_mapping: {
-            emailAddress: 'mail',
-            firstName: 'givenName',
-          },
+        saml_attribute_mapping: {
+          emailAddress: 'mail',
+          firstName: 'givenName',
         },
       },
     });

packages/localizations/src/en-US.ts

@@ -204,6 +204,26 @@ export const enUS: LocalizationResource = {
     navbar: {
       title: 'Configure Single Sign-On (SSO)',
     },
+    verifyEmailDomainStep: {
+      title: 'Verify email address',
+      subtitle: 'Verify the email address you want to enable the enterprise connection on.',
+      addEmailAddress: {
+        formTitle: 'We need your email',
+        formSubtitle: 'In order to start we will need your email address',
+        inputPlaceholder: 'name@company.com',
+        inputLabel: 'Email address',
+      },
+      emailCode: {
+        formTitle: 'Verify your email address',
+        formSubtitle: 'Enter the verification code sent to {{identifier}}',
+        resendButton: "Didn't receive a code? Resend",
+        verified: {
+          title: 'We got your email',
+          subtitle: "You've verified your email address with the following email",
+          inputLabel: 'Verified email address',
+        },
+      },
+    },
   },
   createOrganization: {
     formButtonSubmit: 'Create organization',

packages/shared/src/internal/clerk-js/warnings.ts

@@ -64,6 +64,8 @@ const warnings = {
     'The <APIKeys/> component cannot be rendered when organization API keys are disabled. Since organization API keys are disabled, this is no-op.',
   cannotRenderOAuthConsentComponentWhenUserDoesNotExist:
     '<OAuthConsent/> cannot render unless a user is signed in. Since no user is signed in, this is no-op.',
+  cannotRenderConfigureSSOComponentWhenUserDoesNotExist:
+    '<ConfigureSSO/> cannot render unless a user is signed in. Since no user is signed in, this is no-op.',
   cannotRenderConfigureSSOComponentWhenDisabled:
     'The <ConfigureSSO/> component cannot be rendered when self-serve SSO is disabled. Visit `https://dashboard.clerk.com` to enable the feature. Since self-serve SSO is disabled, this is no-op.',
   cannotRenderConfigureSSOComponentWhenEmailAddressDisabled:

packages/shared/src/types/localization.ts

@@ -1296,6 +1296,26 @@ export type __internal_LocalizationResource = {
     navbar: {
       title: LocalizationValue;
     };
+    verifyEmailDomainStep: {
+      title: LocalizationValue;
+      subtitle: LocalizationValue;
+      addEmailAddress: {
+        formTitle: LocalizationValue;
+        formSubtitle: LocalizationValue;
+        inputPlaceholder: LocalizationValue;
+        inputLabel: LocalizationValue;
+      };
+      emailCode: {
+        formTitle: LocalizationValue;
+        formSubtitle: LocalizationValue<'identifier'>;
+        resendButton: LocalizationValue;
+        verified: {
+          title: LocalizationValue;
+          subtitle: LocalizationValue;
+          inputLabel: LocalizationValue;
+        };
+      };
+    };
   };
   apiKeys: {
     formTitle: LocalizationValue;

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

@@ -1,26 +1,35 @@
-import { useOrganization } from '@clerk/shared/react/index';
+import { __internal_useUserEnterpriseConnections, useOrganization, useUser } from '@clerk/shared/react';
 import type { __experimental_ConfigureSSOProps } from '@clerk/shared/types';
 import React from 'react';
 
 import { useEnvironment, withCoreUserGuard } from '@/contexts';
-import { Box, Col, Flex, Flow, Icon, localizationKeys, Text, useAppearance } from '@/customizables';
+import { Box, Col, descriptors, Flex, Flow, Icon, localizationKeys, Text, useAppearance } from '@/customizables';
 import { ApplicationLogo } from '@/elements/ApplicationLogo';
 import { withCardStateProvider } from '@/elements/contexts';
 import { NavBar, NavbarContextProvider } from '@/elements/Navbar';
 import { ProfileCard } from '@/elements/ProfileCard';
 import { BoxIcon } from '@/icons';
 import { Route, Switch } from '@/router';
 
+import { ConfigureSSOFlowProvider } from './ConfigureSSOContext';
+import {
+  ConfigureCreateApp,
+  ConfirmationStep,
+  ProvideEmail,
+  SelectProviderStep,
+  TestConfigurationStep,
+  VerifyDomainStep,
+} from './steps';
+import { ConfigureSSOWizard } from './wizard';
+
 const ConfigureSSOInternal = () => {
   return (
     <Flow.Root flow='configureSSO'>
-      <Flow.Part>
-        <Switch>
-          <Route>
-            <AuthenticatedContent />
-          </Route>
-        </Switch>
-      </Flow.Part>
+      <Switch>
+        <Route>
+          <AuthenticatedContent />
+        </Route>
+      </Switch>
     </Flow.Root>
   );
 };
@@ -32,6 +41,17 @@ const AuthenticatedContent = withCoreUserGuard(() => {
   const { parsedOptions } = useAppearance();
   const hasLogo = Boolean(parsedOptions.logoImageUrl || logoImageUrl);
 
+  const {
+    data: enterpriseConnections,
+    isLoading: isLoadingEnterpriseConnections,
+    createEnterpriseConnection,
+    updateEnterpriseConnection,
+    deleteEnterpriseConnection,
+    revalidate: revalidateEnterpriseConnections,
+  } = __internal_useUserEnterpriseConnections({ enabled: true });
+  // Currently FAPI only supports one enterprise connection per user
+  const enterpriseConnection = enterpriseConnections?.[0];
+
   return (
     <ProfileCard.Root
       sx={t => ({ display: 'grid', gridTemplateColumns: '1fr 3fr', height: t.sizes.$176, overflow: 'hidden' })}
@@ -89,12 +109,100 @@ const AuthenticatedContent = withCoreUserGuard(() => {
           routes={[]}
           contentRef={contentRef}
         />
-        <ProfileCard.Content contentRef={contentRef} />
+        <Col
+          ref={contentRef}
+          elementDescriptor={descriptors.scrollBox}
+          sx={t => ({
+            backgroundColor: t.colors.$colorBackground,
+            position: 'relative',
+            borderRadius: t.radii.$lg,
+            width: '100%',
+            overflow: 'hidden',
+            borderWidth: t.borderWidths.$normal,
+            borderStyle: t.borderStyles.$solid,
+            borderColor: t.colors.$borderAlpha150,
+            marginBlock: '-1px',
+            marginInlineEnd: '-1px',
+            flex: 1,
+          })}
+        >
+          <ConfigureSSOFlowProvider
+            enterpriseConnection={enterpriseConnection}
+            isLoading={isLoadingEnterpriseConnections}
+            createEnterpriseConnection={createEnterpriseConnection}
+            updateEnterpriseConnection={updateEnterpriseConnection}
+            deleteEnterpriseConnection={deleteEnterpriseConnection}
+            revalidate={revalidateEnterpriseConnections}
+          >
+            <ConfigureSSOSteps />
+          </ConfigureSSOFlowProvider>
+        </Col>
       </NavbarContextProvider>
     </ProfileCard.Root>
   );
 });
 
+const ConfigureSSOSteps = () => {
+  const { user } = useUser();
+
+  const hasEmailAddress = Boolean(user?.emailAddresses?.length);
+
+  return (
+    <ConfigureSSOWizard>
+      <ConfigureSSOWizard.Step
+        id='select-provider'
+        path='select-provider'
+        label='Select provider'
+      >
+        <SelectProviderStep />
+      </ConfigureSSOWizard.Step>
+      <ConfigureSSOWizard.Step
+        id='verify-email-domain'
+        path='verify-email-domain'
+        label='Verify domain'
+      >
+        <ConfigureSSOWizard>
+          {!hasEmailAddress && (
+            <ConfigureSSOWizard.Step
+              id='provide-email'
+              path='provide-email'
+            >
+              <ProvideEmail />
+            </ConfigureSSOWizard.Step>
+          )}
+          <ConfigureSSOWizard.Step
+            id='verify-domain'
+            path='verify-domain'
+          >
+            <VerifyDomainStep />
+          </ConfigureSSOWizard.Step>
+        </ConfigureSSOWizard>
+      </ConfigureSSOWizard.Step>
+      <ConfigureSSOWizard.Step
+        id='configure'
+        path='configure'
+        label='Configure'
+      >
+        <ConfigureCreateApp />
+      </ConfigureSSOWizard.Step>
+      <ConfigureSSOWizard.Step
+        id='test'
+        path='test'
+        label='Test'
+      >
+        <TestConfigurationStep />
+      </ConfigureSSOWizard.Step>
+      <ConfigureSSOWizard.Step
+        id='confirmation'
+        path='confirmation'
+        label='Confirmation'
+      >
+        <ConfirmationStep />
+      </ConfigureSSOWizard.Step>
+    </ConfigureSSOWizard>
+  );
+};
+
 const OrganizationSidebarSubtitle = () => {
   const { organization } = useOrganization();