feat(clerk-js,types,localizations): Choose enterprise connection on sign-in/sign-up (#6947)

Author: LauraBeatris

.changeset/upset-results-win.md

@@ -0,0 +1,7 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Introduce experimental step to choose enterprise connection on sign-in/sign-up

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -127,6 +127,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/sign-in-signal-value.mdx",
   "types/sign-out.mdx",
   "types/sign-up-authenticate-with-metamask-params.mdx",
+  "types/sign-up-enterprise-connection-json.mdx",
+  "types/sign-up-enterprise-connection-resource.mdx",
   "types/sign-up-future-resource.mdx",
   "types/sign-up-resource.mdx",
   "types/signed-in-session-resource.mdx",

packages/clerk-js/bundlewatch.config.json

@@ -16,7 +16,7 @@
     { "path": "./dist/organizationswitcher*.js", "maxSize": "5KB" },
     { "path": "./dist/organizationlist*.js", "maxSize": "5.5KB" },
     { "path": "./dist/signin*.js", "maxSize": "18KB" },
-    { "path": "./dist/signup*.js", "maxSize": "8.86KB" },
+    { "path": "./dist/signup*.js", "maxSize": "9.5KB" },
     { "path": "./dist/userbutton*.js", "maxSize": "5KB" },
     { "path": "./dist/userprofile*.js", "maxSize": "16KB" },
     { "path": "./dist/userverification*.js", "maxSize": "5KB" },

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

@@ -222,6 +222,7 @@ export class SignIn extends BaseResource implements SignInResource {
           redirectUrl: params.redirectUrl,
           actionCompleteRedirectUrl: params.actionCompleteRedirectUrl,
           oidcPrompt: params.oidcPrompt,
+          enterpriseConnectionId: params.enterpriseConnectionId,
         } as EnterpriseSSOConfig;
         break;
       default:
@@ -308,7 +309,8 @@ export class SignIn extends BaseResource implements SignInResource {
     params: AuthenticateWithRedirectParams,
     navigateCallback: (url: URL | string) => void,
   ): Promise<void> => {
-    const { strategy, redirectUrlComplete, identifier, oidcPrompt, continueSignIn } = params || {};
+    const { strategy, redirectUrlComplete, identifier, oidcPrompt, continueSignIn, enterpriseConnectionId } =
+      params || {};
     const actionCompleteRedirectUrl = redirectUrlComplete;
 
     const redirectUrl = SignIn.clerk.buildUrlWithAuth(params.redirectUrl);
@@ -328,6 +330,7 @@ export class SignIn extends BaseResource implements SignInResource {
         redirectUrl,
         actionCompleteRedirectUrl,
         oidcPrompt,
+        enterpriseConnectionId,
       });
     }
 

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

@@ -16,6 +16,8 @@ import type {
   PrepareWeb3WalletVerificationParams,
   SignUpAuthenticateWithWeb3Params,
   SignUpCreateParams,
+  SignUpEnterpriseConnectionJSON,
+  SignUpEnterpriseConnectionResource,
   SignUpField,
   SignUpFutureCreateParams,
   SignUpFutureEmailCodeVerifyParams,
@@ -385,6 +387,7 @@ export class SignUp extends BaseResource implements SignUpResource {
       emailAddress,
       legalAccepted,
       oidcPrompt,
+      enterpriseConnectionId,
     } = params;
 
     const redirectUrlWithAuthToken = SignUp.clerk.buildUrlWithAuth(redirectUrl);
@@ -398,6 +401,7 @@ export class SignUp extends BaseResource implements SignUpResource {
         emailAddress,
         legalAccepted,
         oidcPrompt,
+        enterpriseConnectionId,
       };
       return continueSignUp && this.id ? this.update(authParams) : this.create(authParams);
     };
@@ -551,6 +555,17 @@ export class SignUp extends BaseResource implements SignUpResource {
 
     return false;
   }
+
+  __experimental_getEnterpriseConnections = (): Promise<SignUpEnterpriseConnectionResource[]> => {
+    return BaseResource._fetch({
+      path: `/client/sign_ups/${this.id}/enterprise_connections`,
+      method: 'GET',
+    }).then(res => {
+      const enterpriseConnections = res?.response as unknown as SignUpEnterpriseConnectionJSON[];
+
+      return enterpriseConnections.map(enterpriseConnection => new SignUpEnterpriseConnection(enterpriseConnection));
+    });
+  };
 }
 
 class SignUpFuture implements SignUpFutureResource {
@@ -889,3 +904,22 @@ class SignUpFuture implements SignUpFutureResource {
     });
   }
 }
+
+class SignUpEnterpriseConnection extends BaseResource implements SignUpEnterpriseConnectionResource {
+  id!: string;
+  name!: string;
+
+  constructor(data: SignUpEnterpriseConnectionJSON) {
+    super();
+    this.fromJSON(data);
+  }
+
+  protected fromJSON(data: SignUpEnterpriseConnectionJSON | null): this {
+    if (data) {
+      this.id = data.id;
+      this.name = data.name;
+    }
+
+    return this;
+  }
+}

packages/clerk-js/src/ui/common/ChooseEnterpriseConnectionCard.tsx

@@ -0,0 +1,123 @@
+import { useState } from 'react';
+
+import type { LocalizationKey } from '@/ui/customizables';
+import { descriptors, Flex, Grid, SimpleButton, Spinner, Text } from '@/ui/customizables';
+import { Card } from '@/ui/elements/Card';
+import { useCardState } from '@/ui/elements/contexts';
+import { Header } from '@/ui/elements/Header';
+import type { InternalTheme, PropsOfComponent } from '@/ui/styledSystem';
+
+type ChooseEnterpriseConnectionCardProps = {
+  title: LocalizationKey;
+  subtitle: LocalizationKey;
+  onClick: (id: string) => Promise<void>;
+  enterpriseConnections: Array<{ id: string; name: string }>;
+};
+
+/**
+ * @experimental
+ */
+export const ChooseEnterpriseConnectionCard = ({
+  title,
+  subtitle,
+  onClick,
+  enterpriseConnections,
+}: ChooseEnterpriseConnectionCardProps) => {
+  const card = useCardState();
+
+  return (
+    <Card.Root>
+      <Card.Content>
+        <Header.Root showLogo>
+          <Header.Title localizationKey={title} />
+          <Header.Subtitle localizationKey={subtitle} />
+        </Header.Root>
+        <Card.Alert>{card.error}</Card.Alert>
+
+        <Grid
+          elementDescriptor={descriptors.enterpriseConnectionsRoot}
+          gap={2}
+        >
+          {enterpriseConnections?.map(({ id, name }) => (
+            <ChooseEnterpriseConnectionButton
+              key={id}
+              id={id}
+              label={name}
+              onClick={onClick}
+            />
+          ))}
+        </Grid>
+      </Card.Content>
+
+      <Card.Footer />
+    </Card.Root>
+  );
+};
+
+type ChooseEnterpriseConnectionButtonProps = Omit<PropsOfComponent<typeof SimpleButton>, 'onClick'> & {
+  id: string;
+  label?: string;
+  onClick: (id: string) => Promise<void>;
+};
+
+const ChooseEnterpriseConnectionButton = (props: ChooseEnterpriseConnectionButtonProps): JSX.Element => {
+  const { label, onClick, ...rest } = props;
+  const [isLoading, setIsLoading] = useState(false);
+
+  const handleClick = () => {
+    setIsLoading(true);
+    void onClick(props.id).catch(() => setIsLoading(false));
+  };
+
+  return (
+    <SimpleButton
+      elementDescriptor={descriptors.enterpriseConnectionButton}
+      variant='outline'
+      block
+      isLoading={isLoading}
+      hoverAsFocus
+      onClick={handleClick}
+      {...rest}
+      sx={(theme: InternalTheme) => [
+        {
+          gap: theme.space.$4,
+          position: 'relative',
+          justifyContent: 'flex-start',
+        },
+        (rest as any).sx,
+      ]}
+    >
+      <Flex
+        justify='center'
+        align='center'
+        as='span'
+        gap={3}
+        sx={{
+          width: '100%',
+          overflow: 'hidden',
+        }}
+      >
+        {isLoading && (
+          <Flex
+            as='span'
+            center
+            sx={(theme: InternalTheme) => ({ flex: `0 0 ${theme.space.$4}` })}
+          >
+            <Spinner
+              size='sm'
+              elementDescriptor={descriptors.spinner}
+            />
+          </Flex>
+        )}
+        <Text
+          elementDescriptor={descriptors.enterpriseConnectionButtonText}
+          as='span'
+          truncate
+          variant='buttonLarge'
+        >
+          {label}
+        </Text>
+      </Flex>
+    </SimpleButton>
+  );
+};

packages/clerk-js/src/ui/components/SignIn/SignInFactorOne.tsx

@@ -12,9 +12,11 @@ import { useAlternativeStrategies } from '../../hooks/useAlternativeStrategies';
 import { localizationKeys } from '../../localization';
 import { useRouter } from '../../router';
 import { AlternativeMethods } from './AlternativeMethods';
+import { hasMultipleEnterpriseConnections } from './shared';
 import { SignInFactorOneAlternativePhoneCodeCard } from './SignInFactorOneAlternativePhoneCodeCard';
 import { SignInFactorOneEmailCodeCard } from './SignInFactorOneEmailCodeCard';
 import { SignInFactorOneEmailLinkCard } from './SignInFactorOneEmailLinkCard';
+import { SignInFactorOneEnterpriseConnections } from './SignInFactorOneEnterpriseConnections';
 import { SignInFactorOneForgotPasswordCard } from './SignInFactorOneForgotPasswordCard';
 import { SignInFactorOnePasskey } from './SignInFactorOnePasskey';
 import { SignInFactorOnePasswordCard } from './SignInFactorOnePasswordCard';
@@ -122,6 +124,15 @@ function SignInFactorOneInternal(): JSX.Element {
       prevCurrentFactor: prev.currentFactor,
     }));
   };
+
+  /**
+   * Prompt to choose between a list of enterprise connections as supported first factors
+   * @experimental
+   */
+  if (hasMultipleEnterpriseConnections(signIn.supportedFirstFactors)) {
+    return <SignInFactorOneEnterpriseConnections />;
+  }
+
   if (showAllStrategies || showForgotPasswordStrategies) {
     const canGoBack = factorHasLocalStrategy(currentFactor);
 

packages/clerk-js/src/ui/components/SignIn/SignInFactorOneEnterpriseConnections.tsx

@@ -0,0 +1,82 @@
+import { useClerk } from '@clerk/shared/react/index';
+import type { ComponentType } from 'react';
+
+import { buildSSOCallbackURL, withRedirect } from '@/ui/common';
+import { ChooseEnterpriseConnectionCard } from '@/ui/common/ChooseEnterpriseConnectionCard';
+import { useCoreSignIn, useEnvironment, useSignInContext } from '@/ui/contexts';
+import { Flow, localizationKeys } from '@/ui/customizables';
+import { withCardStateProvider } from '@/ui/elements/contexts';
+import type { AvailableComponentProps } from '@/ui/types';
+
+import { hasMultipleEnterpriseConnections } from './shared';
+
+/**
+ * @experimental
+ */
+const SignInFactorOneEnterpriseConnectionsInternal = () => {
+  const ctx = useSignInContext();
+  const { displayConfig } = useEnvironment();
+
+  const clerk = useClerk();
+  const signIn = clerk.client.signIn;
+
+  if (!hasMultipleEnterpriseConnections(signIn.supportedFirstFactors)) {
+    // This should not happen due to the HOC guard, but provides type safety
+    return null;
+  }
+
+  const enterpriseConnections = signIn.supportedFirstFactors.map(ff => ({
+    id: ff.enterpriseConnectionId,
+    name: ff.enterpriseConnectionName,
+  }));
+
+  const handleEnterpriseSSO = (enterpriseConnectionId: string) => {
+    const redirectUrl = buildSSOCallbackURL(ctx, displayConfig.signInUrl);
+    const redirectUrlComplete = ctx.afterSignInUrl || '/';
+
+    return signIn.authenticateWithRedirect({
+      strategy: 'enterprise_sso',
+      redirectUrl,
+      redirectUrlComplete,
+      oidcPrompt: ctx.oidcPrompt,
+      continueSignIn: true,
+      enterpriseConnectionId,
+    });
+  };
+
+  return (
+    <Flow.Part part='enterpriseConnections'>
+      <ChooseEnterpriseConnectionCard
+        title={localizationKeys('signIn.enterpriseConnections.title')}
+        subtitle={localizationKeys('signIn.enterpriseConnections.subtitle')}
+        onClick={handleEnterpriseSSO}
+        enterpriseConnections={enterpriseConnections}
+      />
+    </Flow.Part>
+  );
+};
+
+const withEnterpriseConnectionsGuard = <P extends AvailableComponentProps>(Component: ComponentType<P>) => {
+  const displayName = Component.displayName || Component.name || 'Component';
+  Component.displayName = displayName;
+
+  const HOC = (props: P) => {
+    const signIn = useCoreSignIn();
+    const signInCtx = useSignInContext();
+
+    return withRedirect(
+      Component,
+      () => !hasMultipleEnterpriseConnections(signIn.supportedFirstFactors),
+      ({ clerk }) => signInCtx.signInUrl || clerk.buildSignInUrl(),
+      'There are no enterprise connections available to sign-in. Clerk is redirecting to the `signInUrl` instead.',
+    )(props);
+  };
+
+  HOC.displayName = `withEnterpriseConnectionsGuard(${displayName})`;
+
+  return HOC;
+};
+
+export const SignInFactorOneEnterpriseConnections = withCardStateProvider(
+  withEnterpriseConnectionsGuard(SignInFactorOneEnterpriseConnectionsInternal),
+);