fix(ui): address OIDC configuration review feedback

Author: NicolasLopes7

.changeset/cool-dragons-march.md

@@ -1,2 +1,8 @@
 ---
+"@clerk/clerk-js": patch
+"@clerk/localizations": patch
+"@clerk/shared": patch
+"@clerk/ui": patch
 ---
+
+Add support for configuring custom OpenID Connect enterprise connections through the Organization Profile.

.changeset/spotty-items-dream.md

@@ -17,20 +17,3 @@ Clerk's JavaScript SDK and library monorepo.
 - For the Mosaic design system (tokens, CVA utility, `MosaicProvider`, migration from existing system), see `references/mosaic-architecture.md`.
 - For dev setup, testing, JSDoc/Typedoc, publishing, changesets, and commit conventions, see `docs/CONTRIBUTING.md`.
 - For working in the repo day to day (setup ordering and footguns, the package map, dev-loop recipes, and the breaking-change checklist), the `clerk-monorepo` Claude Code skill in `.claude/skills/clerk-monorepo/` restates these rules in actionable form.
-
-<claude-mem-context>
-# Memory Context
-
-# claude-mem status
-
-This project has no memory yet. The current session will seed it; subsequent sessions will receive auto-injected context for relevant past work.
-
-Memory injection starts on your second session in a project.
-
-`/learn-codebase` is available if the user wants to front-load the entire repo into memory in a single pass (~5 minutes on a typical repo, optional). Otherwise memory builds passively as work happens.
-
-Live activity: http://localhost:37701
-How it works: `/how-it-works`
-
-This message disappears once the first observation lands.
-</claude-mem-context>

AGENTS.md

@@ -38,9 +38,6 @@ export type FieldId =
   | 'clientId'
   | 'clientSecret'
   | 'redirectUri'
-  | 'oidcClientId'
-  | 'oidcClientSecret'
-  | 'oidcRedirectUri'
   | 'acsUrl'
   | 'spEntityId'
   | 'web3WalletName'

packages/shared/src/types/elementIds.ts

@@ -58,7 +58,10 @@ const fullyConfiguredSaml = makeSamlConnection({
   idpMetadataUrl: 'https://idp.example.com/metadata',
 });
 
-const configuredOidc = makeOauthConfig({ clientId: 'client_abc' });
+const configuredOidc = makeOauthConfig({
+  clientId: 'client_abc',
+  discoveryUrl: 'https://idp.example.com/.well-known/openid-configuration',
+});
 
 const makeOidcConnection = (overrides: Partial<EnterpriseConnectionResource> = {}): EnterpriseConnectionResource =>
   makeConnection({ provider: 'oauth_custom_acme', samlConnection: null, oauthConfig: configuredOidc, ...overrides });
@@ -141,9 +144,28 @@ describe('organizationEnterpriseConnection', () => {
         }).hasMinimumConfiguration,
       ).toBe(false);
     });
-    it('oidc client id present → true', () => {
+    it('oidc client id and discovery URL present → true', () => {
       expect(derive({ connection: makeOidcConnection() }).hasMinimumConfiguration).toBe(true);
     });
+    it('oidc client id without endpoints → false', () => {
+      expect(
+        derive({ connection: makeOidcConnection({ oauthConfig: makeOauthConfig({ clientId: 'client_abc' }) }) })
+          .hasMinimumConfiguration,
+      ).toBe(false);
+    });
+    it('oidc client id with manual authorization and token URLs → true', () => {
+      expect(
+        derive({
+          connection: makeOidcConnection({
+            oauthConfig: makeOauthConfig({
+              clientId: 'client_abc',
+              authUrl: 'https://idp.example.com/authorize',
+              tokenUrl: 'https://idp.example.com/token',
+            }),
+          }),
+        }).hasMinimumConfiguration,
+      ).toBe(true);
+    });
     it('oidc without oauth config → false', () => {
       expect(derive({ connection: makeOidcConnection({ oauthConfig: null }) }).hasMinimumConfiguration).toBe(false);
     });
@@ -294,9 +316,29 @@ describe('isEnterpriseConnectionConfigured', () => {
   it('oidc with empty client id → false', () => {
     expect(isEnterpriseConnectionConfigured(makeOidcConnection({ oauthConfig: makeOauthConfig() }))).toBe(false);
   });
-  it('oidc with client id present → true', () => {
+  it('oidc with client id and discovery URL present → true', () => {
     expect(isEnterpriseConnectionConfigured(makeOidcConnection())).toBe(true);
   });
+  it('oidc with client id but no endpoints → false', () => {
+    expect(
+      isEnterpriseConnectionConfigured(
+        makeOidcConnection({ oauthConfig: makeOauthConfig({ clientId: 'client_abc' }) }),
+      ),
+    ).toBe(false);
+  });
+  it('oidc with client id and manual authorization and token URLs → true', () => {
+    expect(
+      isEnterpriseConnectionConfigured(
+        makeOidcConnection({
+          oauthConfig: makeOauthConfig({
+            clientId: 'client_abc',
+            authUrl: 'https://idp.example.com/authorize',
+            tokenUrl: 'https://idp.example.com/token',
+          }),
+        }),
+      ),
+    ).toBe(true);
+  });
   it('branches on provider: an oidc connection is not satisfied by saml fields', () => {
     expect(
       isEnterpriseConnectionConfigured(

packages/ui/src/components/ConfigureSSO/domain/__tests__/organizationEnterpriseConnection.test.ts

@@ -58,7 +58,10 @@ export const isEnterpriseConnectionConfigured = (
     return false;
   }
   if (isOidcProvider(connection.provider)) {
-    return Boolean(connection.oauthConfig?.clientId);
+    const oauthConfig = connection.oauthConfig;
+    return Boolean(
+      oauthConfig?.clientId && (oauthConfig.discoveryUrl || (oauthConfig.authUrl && oauthConfig.tokenUrl)),
+    );
   }
   return Boolean(connection.samlConnection?.idpSsoUrl && connection.samlConnection?.idpEntityId);
 };

packages/ui/src/components/ConfigureSSO/domain/organizationEnterpriseConnection.ts

@@ -1,9 +1,10 @@
+import { ClerkAPIResponseError } from '@clerk/shared/error';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { Flow } from '@/customizables';
 import { bindCreateFixtures } from '@/test/create-fixtures';
 import { render, screen } from '@/test/utils';
-import { CardStateProvider } from '@/ui/elements/contexts';
+import { CardStateProvider, useCardState } from '@/ui/elements/contexts';
 
 import type { EnterpriseConnectionProviderType } from '../../../types';
 
@@ -12,6 +13,7 @@ import type { EnterpriseConnectionProviderType } from '../../../types';
 // left undefined so that footer self-hides in this isolated render.
 const contextState = vi.hoisted(() => ({
   provider: undefined as string | undefined,
+  isOIDCFlowEnabled: true,
   enterpriseConnection: undefined as
     | {
         id: string;
@@ -27,6 +29,12 @@ const contextState = vi.hoisted(() => ({
 }));
 const updateConnection = vi.hoisted(() => vi.fn());
 
+const CardErrorProbe = () => {
+  const { error } = useCardState();
+
+  return error ? <div>{error}</div> : null;
+};
+
 vi.mock('../../../ConfigureSSOContext', () => ({
   useConfigureSSO: () => ({
     enterpriseConnection: contextState.enterpriseConnection,
@@ -36,6 +44,7 @@ vi.mock('../../../ConfigureSSOContext', () => ({
       provider: contextState.provider,
       hasConnection: true,
     },
+    isOIDCFlowEnabled: contextState.isOIDCFlowEnabled,
   }),
 }));
 
@@ -52,28 +61,34 @@ const { createFixtures } = bindCreateFixtures('ConfigureSSO');
 
 describe('resolveConfigureSteps', () => {
   it('dispatches custom and legacy OIDC provider keys to the OIDC sub-flow', () => {
-    expect(resolveConfigureSteps('oauth_custom_clerk_dev')).toBe(OidcCustomConfigureSteps);
-    expect(resolveConfigureSteps('oidc_clerk_dev')).toBe(OidcCustomConfigureSteps);
-    expect(resolveConfigureSteps('oidc_ghe_acme')).toBe(OidcCustomConfigureSteps);
-    expect(resolveConfigureSteps('oidc_gitlab_ent_acme')).toBe(OidcCustomConfigureSteps);
-    expect(resolveConfigureSteps('oidc_custom')).toBe(OidcCustomConfigureSteps);
+    expect(resolveConfigureSteps('oauth_custom_clerk_dev', true)).toBe(OidcCustomConfigureSteps);
+    expect(resolveConfigureSteps('oidc_clerk_dev', true)).toBe(OidcCustomConfigureSteps);
+    expect(resolveConfigureSteps('oidc_ghe_acme', true)).toBe(OidcCustomConfigureSteps);
+    expect(resolveConfigureSteps('oidc_gitlab_ent_acme', true)).toBe(OidcCustomConfigureSteps);
+    expect(resolveConfigureSteps('oidc_custom', true)).toBe(OidcCustomConfigureSteps);
+  });
+
+  it('does not dispatch OIDC providers while the experimental flow is disabled', () => {
+    expect(resolveConfigureSteps('oauth_custom_clerk_dev', false)).toBeUndefined();
+    expect(resolveConfigureSteps('oidc_clerk_dev', false)).toBeUndefined();
   });
 
   it('dispatches SAML providers by exact literal', () => {
-    expect(resolveConfigureSteps('saml_okta')).toBe(SamlOktaConfigureSteps);
-    expect(resolveConfigureSteps('saml_custom')).toBe(SamlCustomConfigureSteps);
-    expect(resolveConfigureSteps('saml_google')).toBe(SamlGoogleConfigureSteps);
-    expect(resolveConfigureSteps('saml_microsoft')).toBe(SamlMicrosoftConfigureSteps);
+    expect(resolveConfigureSteps('saml_okta', false)).toBe(SamlOktaConfigureSteps);
+    expect(resolveConfigureSteps('saml_custom', false)).toBe(SamlCustomConfigureSteps);
+    expect(resolveConfigureSteps('saml_google', false)).toBe(SamlGoogleConfigureSteps);
+    expect(resolveConfigureSteps('saml_microsoft', false)).toBe(SamlMicrosoftConfigureSteps);
   });
 
   it('returns undefined for an unrecognized provider so the caller can degrade', () => {
-    expect(resolveConfigureSteps('ldap_enterprise' as EnterpriseConnectionProviderType)).toBeUndefined();
+    expect(resolveConfigureSteps('ldap_enterprise' as EnterpriseConnectionProviderType, true)).toBeUndefined();
   });
 });
 
 describe('ConfigureProviderStep', () => {
   beforeEach(() => {
     contextState.provider = undefined;
+    contextState.isOIDCFlowEnabled = true;
     contextState.enterpriseConnection = undefined;
     updateConnection.mockReset();
   });
@@ -83,6 +98,7 @@ describe('ConfigureProviderStep', () => {
       <Flow.Root flow='configureSSO'>
         <CardStateProvider>
           <ConfigureProviderStep />
+          <CardErrorProbe />
         </CardStateProvider>
       </Flow.Root>,
       { wrapper },
@@ -211,6 +227,36 @@ describe('ConfigureProviderStep', () => {
     });
   });
 
+  it('clears endpoint API errors when switching configuration modes', async () => {
+    contextState.provider = 'oidc_clerk_dev';
+    contextState.enterpriseConnection = { id: 'ent_123', oauthConfig: null };
+    updateConnection.mockRejectedValueOnce(
+      new ClerkAPIResponseError('Error', {
+        data: [
+          {
+            code: 'form_param_invalid',
+            long_message: 'The endpoint configuration is invalid.',
+            message: 'The endpoint configuration is invalid.',
+          },
+        ],
+        status: 422,
+      }),
+    );
+    const { wrapper } = await createFixtures();
+
+    const { userEvent } = renderStep(wrapper);
+
+    await userEvent.click(await screen.findByRole('button', { name: 'Continue' }));
+    await userEvent.type(screen.getByRole('textbox', { name: 'Discovery endpoint' }), 'https://idp.example/discovery');
+    await userEvent.click(screen.getByRole('button', { name: 'Continue' }));
+
+    expect(await screen.findByText('The endpoint configuration is invalid.')).toBeInTheDocument();
+
+    await userEvent.click(screen.getByRole('radio', { name: 'Configure manually' }));
+
+    expect(screen.queryByText('The endpoint configuration is invalid.')).not.toBeInTheDocument();
+  });
+
   it('saves credentials before advancing', async () => {
     contextState.provider = 'oidc_clerk_dev';
     contextState.enterpriseConnection = { id: 'ent_123', oauthConfig: null };
@@ -241,6 +287,53 @@ describe('ConfigureProviderStep', () => {
     });
   });
 
+  it('displays credential API errors on their matching fields', async () => {
+    contextState.provider = 'oidc_clerk_dev';
+    contextState.enterpriseConnection = { id: 'ent_123', oauthConfig: null };
+    updateConnection.mockReset();
+    updateConnection.mockResolvedValueOnce({});
+    updateConnection.mockRejectedValueOnce(
+      new ClerkAPIResponseError('Error', {
+        data: [
+          {
+            code: 'form_param_invalid',
+            long_message: 'Client ID is invalid.',
+            message: 'Client ID is invalid.',
+            meta: { param_name: 'client_id' },
+          },
+          {
+            code: 'form_param_invalid',
+            long_message: 'Client secret is invalid.',
+            message: 'Client secret is invalid.',
+            meta: { param_name: 'client_secret' },
+          },
+        ],
+        status: 422,
+      }),
+    );
+    const { wrapper } = await createFixtures();
+
+    const { userEvent } = renderStep(wrapper);
+
+    await userEvent.click(await screen.findByRole('button', { name: 'Continue' }));
+    await userEvent.type(
+      screen.getByRole('textbox', { name: 'Discovery endpoint' }),
+      'https://idp.example/.well-known/openid-configuration',
+    );
+    await userEvent.click(screen.getByRole('button', { name: 'Continue' }));
+
+    const clientId = await screen.findByRole('textbox', { name: 'Client ID' });
+    const clientSecret = screen.getByLabelText('Client secret');
+    await userEvent.type(clientId, 'client_123');
+    await userEvent.type(clientSecret, 'secret_456');
+    await userEvent.click(screen.getByRole('button', { name: 'Continue' }));
+
+    expect(await screen.findByText('Client ID is invalid.')).toBeInTheDocument();
+    expect(await screen.findByText('Client secret is invalid.')).toBeInTheDocument();
+    expect(clientId).toHaveAttribute('aria-describedby', 'error-clientId');
+    expect(clientSecret).toHaveAttribute('aria-describedby', 'error-clientSecret');
+  });
+
   it('selects manual mode when an existing connection has manual endpoints without a discovery URL', async () => {
     contextState.provider = 'oidc_clerk_dev';
     contextState.enterpriseConnection = {
@@ -324,4 +417,15 @@ describe('ConfigureProviderStep', () => {
 
     expect(await screen.findByText(/unsupported provider/i)).toBeInTheDocument();
   });
+
+  it('degrades to the unsupported-provider state for an existing OIDC connection when the flag is off', async () => {
+    contextState.provider = 'oauth_custom_clerk_dev';
+    contextState.isOIDCFlowEnabled = false;
+    const { wrapper } = await createFixtures();
+
+    renderStep(wrapper);
+
+    expect(await screen.findByText(/unsupported provider/i)).toBeInTheDocument();
+    expect(screen.queryByText(/create a new oidc application/i)).not.toBeInTheDocument();
+  });
 });

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

@@ -28,8 +28,13 @@ const STEPS_BY_SAML_PROVIDER: Record<SamlProviderType, ConfigureStepsComponent>
 
 export const resolveConfigureSteps = (
   provider: EnterpriseConnectionProviderType,
-): ConfigureStepsComponent | undefined =>
-  isOidcProvider(provider) ? OidcCustomConfigureSteps : STEPS_BY_SAML_PROVIDER[provider];
+  isOIDCFlowEnabled: boolean,
+): ConfigureStepsComponent | undefined => {
+  if (isOidcProvider(provider)) {
+    return isOIDCFlowEnabled ? OidcCustomConfigureSteps : undefined;
+  }
+  return STEPS_BY_SAML_PROVIDER[provider];
+};
 
 export const ConfigureStep = (): JSX.Element => {
   const { organizationEnterpriseConnection: c } = useConfigureSSO();
@@ -63,13 +68,13 @@ export const ConfigureStep = (): JSX.Element => {
 };
 
 export const ConfigureProviderStep = (): JSX.Element | null => {
-  const { organizationEnterpriseConnection: c } = useConfigureSSO();
+  const { organizationEnterpriseConnection: c, isOIDCFlowEnabled } = useConfigureSSO();
 
   if (!c.provider) {
     return null;
   }
 
-  const ConfigureSteps = resolveConfigureSteps(c.provider);
+  const ConfigureSteps = resolveConfigureSteps(c.provider, isOIDCFlowEnabled);
 
   return (
     <Flow.Part part='configureCreateApp'>

packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/index.tsx

@@ -12,6 +12,7 @@ const OIDC_STEPS: WizardStepConfig[] = [{ id: 'redirect-uri' }, { id: 'endpoints
 export const OidcCustomConfigureSteps = (): JSX.Element => {
   const { enterpriseConnection } = useConfigureSSO();
   const oauthConfig = enterpriseConnection?.oauthConfig;
+  // Keep mode outside the step so it persists across wizard navigation.
   const [endpointMode, setEndpointMode] = useState<OidcIdpConfigurationMode>(
     oauthConfig?.authUrl && !oauthConfig.discoveryUrl ? 'manual' : 'discoveryUrl',
   );

packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/oidc/OidcCustomConfigureSteps.tsx

@@ -19,13 +19,13 @@ export const OidcCredentialsStep = (): JSX.Element => {
     enterpriseConnection,
     enterpriseConnectionMutations: { updateConnection },
   } = useConfigureSSO();
-  const clientIdField = useFormControl('oidcClientId', enterpriseConnection?.oauthConfig?.clientId ?? '', {
+  const clientIdField = useFormControl('clientId', enterpriseConnection?.oauthConfig?.clientId ?? '', {
     type: 'text',
     label: localizationKeys('configureSSO.configureStep.oidcCustom.credentialsStep.clientId.label'),
     placeholder: localizationKeys('configureSSO.configureStep.oidcCustom.credentialsStep.clientId.placeholder'),
     isRequired: true,
   });
-  const clientSecretField = useFormControl('oidcClientSecret', '', {
+  const clientSecretField = useFormControl('clientSecret', '', {
     type: 'password',
     label: localizationKeys('configureSSO.configureStep.oidcCustom.credentialsStep.clientSecret.label'),
     placeholder: localizationKeys('configureSSO.configureStep.oidcCustom.credentialsStep.clientSecret.placeholder'),