feat(clerk-js,types): Add support for modal SSO sign-ins (#7026)

Author: dstaley

.changeset/ripe-banks-pay.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+[Experimental] Add support for modal SSO sign-ins to new APIs

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

@@ -77,7 +77,11 @@ import {
   getOKXWalletIdentifier,
   windowNavigate,
 } from '../../utils';
-import { _authenticateWithPopup } from '../../utils/authenticateWithPopup';
+import {
+  _authenticateWithPopup,
+  _futureAuthenticateWithPopup,
+  wrapWithPopupRoutes,
+} from '../../utils/authenticateWithPopup';
 import {
   convertJSONToPublicKeyRequestOptions,
   serializePublicKeyCredentialAssertion,
@@ -893,29 +897,52 @@ class SignInFuture implements SignInFutureResource {
   }
 
   async sso(params: SignInFutureSSOParams): Promise<{ error: unknown }> {
-    const { flow = 'auto', strategy, redirectUrl, redirectCallbackUrl } = params;
+    const { strategy, redirectUrl, redirectCallbackUrl, popup, oidcPrompt, enterpriseConnectionId } = params;
     return runAsyncResourceTask(this.resource, async () => {
-      if (flow !== 'auto') {
-        throw new Error('modal flow is not supported yet');
-      }
-
       let actionCompleteRedirectUrl = redirectUrl;
       try {
         new URL(redirectUrl);
       } catch {
         actionCompleteRedirectUrl = window.location.origin + redirectUrl;
       }
 
+      const routes = { redirectUrl: SignIn.clerk.buildUrlWithAuth(redirectCallbackUrl), actionCompleteRedirectUrl };
+      if (popup) {
+        const wrappedRoutes = wrapWithPopupRoutes(SignIn.clerk, {
+          redirectCallbackUrl: routes.redirectUrl,
+          redirectUrl: actionCompleteRedirectUrl,
+        });
+        routes.redirectUrl = wrappedRoutes.redirectCallbackUrl;
+        routes.actionCompleteRedirectUrl = wrappedRoutes.redirectUrl;
+      }
+
       await this._create({
         strategy,
-        redirectUrl: SignIn.clerk.buildUrlWithAuth(redirectCallbackUrl),
-        actionCompleteRedirectUrl,
+        ...routes,
       });
 
+      if (strategy === 'enterprise_sso') {
+        await this.resource.__internal_basePost({
+          body: {
+            ...routes,
+            oidcPrompt,
+            enterpriseConnectionId,
+            strategy: 'enterprise_sso',
+          },
+          action: 'prepare_first_factor',
+        });
+      }
+
       const { status, externalVerificationRedirectURL } = this.resource.firstFactorVerification;
 
       if (status === 'unverified' && externalVerificationRedirectURL) {
-        windowNavigate(externalVerificationRedirectURL);
+        if (popup) {
+          await _futureAuthenticateWithPopup(SignIn.clerk, { popup, externalVerificationRedirectURL });
+          // Pick up the modified SignIn resource
+          await this.resource.reload();
+        } else {
+          windowNavigate(externalVerificationRedirectURL);
+        }
       }
     });
   }

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

@@ -79,3 +79,74 @@ export async function _authenticateWithPopup(
     navigateCallback,
   );
 }
+
+/**
+ * Creates new redirect and callback URLs that point to the `/popup-callback` route on Account Portal. These URLs will
+ * be used by FAPI to redirect after the OAuth flow completes, and will result in a message being sent to the parent
+ * window.
+ */
+export function wrapWithPopupRoutes(
+  client: Clerk,
+  {
+    redirectCallbackUrl,
+    redirectUrl,
+  }: {
+    /**
+     * The route to navigate to if a session was not created.
+     */
+    redirectCallbackUrl: string;
+    /**
+     * The route to navigate to if a session was created.
+     */
+    redirectUrl: string;
+  },
+): { redirectCallbackUrl: string; redirectUrl: string } {
+  const accountPortalHost = buildAccountsBaseUrl(client.frontendApi);
+
+  // We set the force_redirect_url query parameter to ensure that the user is redirected to the correct page even
+  // in situations like a modal transfer flow.
+  const r = new URL(redirectCallbackUrl);
+  r.searchParams.set('sign_in_force_redirect_url', redirectUrl);
+  r.searchParams.set('sign_up_force_redirect_url', redirectUrl);
+  // All URLs are decorated with the dev browser token in development mode since we're moving between AP and the app.
+  const redirectUrlWithForceRedirectUrl = client.buildUrlWithAuth(r.toString());
+
+  const popupRedirectUrlComplete = client.buildUrlWithAuth(`${accountPortalHost}/popup-callback`);
+  const popupRedirectUrl = client.buildUrlWithAuth(
+    `${accountPortalHost}/popup-callback?return_url=${encodeURIComponent(redirectUrlWithForceRedirectUrl)}`,
+  );
+
+  return { redirectCallbackUrl: popupRedirectUrl, redirectUrl: popupRedirectUrlComplete };
+}
+
+export function _futureAuthenticateWithPopup(
+  client: Clerk,
+  params: { popup: { location: { href: string } }; externalVerificationRedirectURL: URL },
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!client.client || !params.popup) {
+      reject();
+      return;
+    }
+
+    const messageHandler = async (event: MessageEvent) => {
+      if (event.origin !== buildAccountsBaseUrl(client.frontendApi)) {
+        return;
+      }
+
+      // The OAuth flow was successful, and we received a message with either a session or a return URL.
+      if (event.data.session || event.data.return_url) {
+        window.removeEventListener('message', messageHandler);
+        resolve();
+      } else {
+        reject();
+      }
+    };
+
+    // Listen for messages from the popup window.
+    window.addEventListener('message', messageHandler);
+
+    // Navigate the popup window to the external verification redirect URL, which kicks off the OAuth flow.
+    params.popup.location.href = params.externalVerificationRedirectURL.toString();
+  });
+}

packages/shared/src/types/signInFuture.ts

@@ -167,8 +167,10 @@ export interface SignInFuturePhoneCodeVerifyParams {
 }
 
 export interface SignInFutureSSOParams {
-  flow?: 'auto' | 'modal';
-  strategy: OAuthStrategy | 'saml' | 'enterprise_sso';
+  /**
+   * The strategy to use for authentication.
+   */
+  strategy: OAuthStrategy | 'enterprise_sso';
   /**
    * The URL to redirect to after the user has completed the SSO flow.
    */
@@ -177,6 +179,30 @@ export interface SignInFutureSSOParams {
    * TODO @revamp-hooks: This should be handled by FAPI instead.
    */
   redirectCallbackUrl: string;
+  /**
+   * If provided, a `Window` to use for the OAuth flow. Useful in instances where you cannot navigate to an
+   * OAuth provider.
+   *
+   * @example
+   * ```ts
+   * const popup = window.open('about:blank', '', 'width=600,height=800');
+   * if (!popup) {
+   *   throw new Error('Failed to open popup');
+   * }
+   * await signIn.sso({ popup, strategy: 'oauth_google', redirectUrl: '/dashboard' });
+   * ```
+   */
+  popup?: { location: { href: string } };
+  /**
+   * Optional for `oauth_<provider>` or `enterprise_sso` strategies. The value to pass to the
+   * [OIDC prompt parameter](https://openid.net/specs/openid-connect-core-1_0.html#:~:text=prompt,reauthentication%20and%20consent.)
+   * in the generated OAuth redirect URL.
+   */
+  oidcPrompt?: string;
+  /**
+   * @experimental
+   */
+  enterpriseConnectionId?: string;
 }
 
 export interface SignInFutureMFAPhoneCodeVerifyParams {