feat(clerk-js): Authenticate with popup

.changeset/serious-tools-double.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Add support for the `oauthFlow` prop on `<SignIn />` and `<SignUp />`, allowing developers to opt-in to using a popup for OAuth authorization instead of redirects.
+
+  With the new `oauthFlow` prop, developers can opt-in to using a popup window instead of redirects for their OAuth flows by setting `oauthFlow` to `"popup"`. While we still recommend the default `"redirect"` for most scenarios, the `"popup"` option is useful in environments where the redirect flow does not currently work, such as when your application is embedded into an `iframe`. We also opt applications into the `"popup"` flow when we detect that your application is running on a domain that's typically embedded into an `iframe`, such as `loveable.app`.

integration/templates/next-app-router/src/app/buttons/page.tsx

@@ -11,6 +11,15 @@ export default function Home() {
         Sign in button (force)
       </SignInButton>
 
+      <SignInButton
+        mode='modal'
+        oauthFlow='popup'
+        forceRedirectUrl='/protected'
+        signUpForceRedirectUrl='/protected'
+      >
+        Sign in button (force, popup)
+      </SignInButton>
+
       <SignInButton
         mode='modal'
         fallbackRedirectUrl='/protected'

integration/tests/oauth-flows.test.ts

@@ -113,4 +113,32 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })('oauth flo
 
     await u.page.waitForAppUrl('/protected');
   });
+
+  test.describe('authenticateWithPopup', () => {
+    test('SignIn with oauthFlow=popup opens popup', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+
+      await u.page.goToRelative('/buttons');
+      await u.page.waitForClerkJsLoaded();
+      await u.po.expect.toBeSignedOut();
+
+      await u.page.getByText('Sign in button (force, popup)').click();
+
+      await u.po.signIn.waitForModal();
+
+      const popupPromise = context.waitForEvent('page');
+      await u.page.getByRole('button', { name: 'E2E OAuth Provider' }).click();
+      const popup = await popupPromise;
+      const popupUtils = createTestUtils({ app, page: popup, context });
+      await popupUtils.page.getByText('Sign in to oauth-provider').waitFor();
+
+      await popupUtils.po.signIn.setIdentifier(fakeUser.email);
+      await popupUtils.po.signIn.continue();
+      await popupUtils.po.signIn.enterTestOtpCode();
+
+      await u.page.waitForAppUrl('/protected');
+
+      await u.po.expect.toBeSignedIn();
+    });
+  });
 });

packages/clerk-js/bundlewatch.config.json

@@ -1,8 +1,8 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "580kB" },
-    { "path": "./dist/clerk.browser.js", "maxSize": "78.6kB" },
-    { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
+    { "path": "./dist/clerk.js", "maxSize": "580.5kB" },
+    { "path": "./dist/clerk.browser.js", "maxSize": "79.25kB" },
+    { "path": "./dist/clerk.headless.js", "maxSize": "55KB" },
     { "path": "./dist/ui-common*.js", "maxSize": "94KB" },
     { "path": "./dist/vendors*.js", "maxSize": "30KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "35.5KB" },
@@ -11,8 +11,8 @@
     { "path": "./dist/organizationprofile*.js", "maxSize": "12KB" },
     { "path": "./dist/organizationswitcher*.js", "maxSize": "5KB" },
     { "path": "./dist/organizationlist*.js", "maxSize": "5.5KB" },
-    { "path": "./dist/signin*.js", "maxSize": "12.4KB" },
-    { "path": "./dist/signup*.js", "maxSize": "6.6KB" },
+    { "path": "./dist/signin*.js", "maxSize": "12.5KB" },
+    { "path": "./dist/signup*.js", "maxSize": "6.75KB" },
     { "path": "./dist/userbutton*.js", "maxSize": "5KB" },
     { "path": "./dist/userprofile*.js", "maxSize": "15KB" },
     { "path": "./dist/userverification*.js", "maxSize": "5KB" },

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

@@ -853,6 +853,17 @@ describe('Clerk singleton', () => {
   });
 
   describe('.handleRedirectCallback()', () => {
+    // handleRedirectCallback calls signIn/signUp.reload, which relies on the global fetch instance. We don't actually
+    // need a return value though, so we just mock a resolved promise.
+    const originalFetch = global.fetch;
+    beforeAll(() => {
+      global.fetch = jest.fn().mockResolvedValue({ json: jest.fn().mockResolvedValue({}) });
+    });
+
+    afterAll(() => {
+      global.fetch = originalFetch;
+    });
+
     beforeEach(() => {
       mockClientFetch.mockReset();
       mockEnvironmentFetch.mockReset();

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

@@ -1489,6 +1489,25 @@ export class Clerk implements ClerkInterface {
       return;
     }
 
+    // If `handleRedirectCallback` is called on a window without an opener property (such as when the OAuth flow popup
+    // directs the opening page to navigate to the /sso-callback route), we need to reload the signIn and signUp resources
+    // to ensure that we have the latest state. This operation can fail when we try reloading a resource that doesn't
+    // exist (such as when reloading a signIn resource during a signUp attempt), but this can be safely ignored.
+    if (!window.opener) {
+      try {
+        await signIn.reload();
+      } catch (err) {
+        console.log('This can be safely ignored:');
+        console.error(err);
+      }
+      try {
+        await signUp.reload();
+      } catch (err) {
+        console.log('This can be safely ignored:');
+        console.error(err);
+      }
+    }
+
     const { displayConfig } = this.environment;
     const { firstFactorVerification } = signIn;
     const { externalAccount } = signUp.verifications;

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

@@ -9,6 +9,7 @@ import type {
   AttemptFirstFactorParams,
   AttemptSecondFactorParams,
   AuthenticateWithPasskeyParams,
+  AuthenticateWithPopupParams,
   AuthenticateWithRedirectParams,
   AuthenticateWithWeb3Params,
   CreateEmailLinkFlowReturn,
@@ -48,6 +49,7 @@ import {
   getOKXWalletIdentifier,
   windowNavigate,
 } from '../../utils';
+import { _authenticateWithPopup } from '../../utils/authenticateWithPopup';
 import {
   convertJSONToPublicKeyRequestOptions,
   serializePublicKeyCredentialAssertion,
@@ -224,7 +226,10 @@ export class SignIn extends BaseResource implements SignInResource {
     });
   };
 
-  public authenticateWithRedirect = async (params: AuthenticateWithRedirectParams): Promise<void> => {
+  private authenticateWithRedirectOrPopup = async (
+    params: AuthenticateWithRedirectParams,
+    navigateCallback: (url: URL | string) => void,
+  ): Promise<void> => {
     const { strategy, redirectUrl, redirectUrlComplete, identifier } = params || {};
 
     const { firstFactorVerification } =
@@ -244,12 +249,26 @@ export class SignIn extends BaseResource implements SignInResource {
     const { status, externalVerificationRedirectURL } = firstFactorVerification;
 
     if (status === 'unverified' && externalVerificationRedirectURL) {
-      windowNavigate(externalVerificationRedirectURL);
+      navigateCallback(externalVerificationRedirectURL);
     } else {
       clerkInvalidFAPIResponse(status, SignIn.fapiClient.buildEmailAddress('support'));
     }
   };
 
+  public authenticateWithRedirect = async (params: AuthenticateWithRedirectParams): Promise<void> => {
+    return this.authenticateWithRedirectOrPopup(params, windowNavigate);
+  };
+
+  public authenticateWithPopup = async (params: AuthenticateWithPopupParams): Promise<void> => {
+    const { popup } = params || {};
+    if (!popup) {
+      clerkMissingOptionError('popup');
+    }
+    return _authenticateWithPopup(SignIn.clerk, this.authenticateWithRedirectOrPopup, params, url => {
+      popup.location.href = url.toString();
+    });
+  };
+
   public authenticateWithWeb3 = async (params: AuthenticateWithWeb3Params): Promise<SignInResource> => {
     if (__BUILD_DISABLE_RHC__) {
       clerkUnsupportedEnvironmentWarning('Web3');

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

@@ -5,6 +5,7 @@ import type {
   AttemptPhoneNumberVerificationParams,
   AttemptVerificationParams,
   AttemptWeb3WalletVerificationParams,
+  AuthenticateWithPopupParams,
   AuthenticateWithRedirectParams,
   AuthenticateWithWeb3Params,
   CreateEmailLinkFlowReturn,
@@ -34,6 +35,7 @@ import {
   getOKXWalletIdentifier,
   windowNavigate,
 } from '../../utils';
+import { _authenticateWithPopup } from '../../utils/authenticateWithPopup';
 import { CaptchaChallenge } from '../../utils/captcha/CaptchaChallenge';
 import { createValidatePassword } from '../../utils/passwords/password';
 import { normalizeUnsafeMetadata } from '../../utils/resourceParams';
@@ -290,27 +292,32 @@ export class SignUp extends BaseResource implements SignUpResource {
     });
   };
 
-  public authenticateWithRedirect = async ({
-    redirectUrl,
-    redirectUrlComplete,
-    strategy,
-    continueSignUp = false,
-    unsafeMetadata,
-    emailAddress,
-    legalAccepted,
-  }: AuthenticateWithRedirectParams & {
-    unsafeMetadata?: SignUpUnsafeMetadata;
-  }): Promise<void> => {
+  private authenticateWithRedirectOrPopup = async (
+    params: AuthenticateWithRedirectParams & {
+      unsafeMetadata?: SignUpUnsafeMetadata;
+    },
+    navigateCallback: (url: URL | string) => void,
+  ): Promise<void> => {
+    const {
+      redirectUrl,
+      redirectUrlComplete,
+      strategy,
+      continueSignUp = false,
+      unsafeMetadata,
+      emailAddress,
+      legalAccepted,
+    } = params;
+
     const authenticateFn = () => {
-      const params = {
+      const authParams = {
         strategy,
         redirectUrl: SignUp.clerk.buildUrlWithAuth(redirectUrl),
         actionCompleteRedirectUrl: redirectUrlComplete,
         unsafeMetadata,
         emailAddress,
         legalAccepted,
       };
-      return continueSignUp && this.id ? this.update(params) : this.create(params);
+      return continueSignUp && this.id ? this.update(authParams) : this.create(authParams);
     };
 
     const { verifications } = await authenticateFn().catch(async e => {
@@ -329,12 +336,35 @@ export class SignUp extends BaseResource implements SignUpResource {
     const { status, externalVerificationRedirectURL } = externalAccount;
 
     if (status === 'unverified' && !!externalVerificationRedirectURL) {
-      windowNavigate(externalVerificationRedirectURL);
+      navigateCallback(externalVerificationRedirectURL);
     } else {
       clerkInvalidFAPIResponse(status, SignUp.fapiClient.buildEmailAddress('support'));
     }
   };
 
+  public authenticateWithRedirect = async (
+    params: AuthenticateWithRedirectParams & {
+      unsafeMetadata?: SignUpUnsafeMetadata;
+    },
+  ): Promise<void> => {
+    return this.authenticateWithRedirectOrPopup(params, windowNavigate);
+  };
+
+  public authenticateWithPopup = async (
+    params: AuthenticateWithPopupParams & {
+      unsafeMetadata?: SignUpUnsafeMetadata;
+    },
+  ): Promise<void> => {
+    const { popup } = params || {};
+    if (!popup) {
+      clerkMissingOptionError('popup');
+    }
+
+    return _authenticateWithPopup(SignUp.clerk, this.authenticateWithRedirectOrPopup, params, url => {
+      popup.location.href = url instanceof URL ? url.toString() : url;
+    });
+  };
+
   update = (params: SignUpUpdateParams): Promise<SignUpResource> => {
     return this._basePatch({
       body: normalizeUnsafeMetadata(params),

packages/clerk-js/src/core/resources/__tests__/__snapshots__/Client.test.ts.snap

@@ -220,7 +220,9 @@ Client {
     "authenticateWithMetamask": [Function],
     "authenticateWithOKXWallet": [Function],
     "authenticateWithPasskey": [Function],
+    "authenticateWithPopup": [Function],
     "authenticateWithRedirect": [Function],
+    "authenticateWithRedirectOrPopup": [Function],
     "authenticateWithWeb3": [Function],
     "create": [Function],
     "createEmailLinkFlow": [Function],
@@ -300,7 +302,9 @@ Client {
     "authenticateWithCoinbaseWallet": [Function],
     "authenticateWithMetamask": [Function],
     "authenticateWithOKXWallet": [Function],
+    "authenticateWithPopup": [Function],
     "authenticateWithRedirect": [Function],
+    "authenticateWithRedirectOrPopup": [Function],
     "authenticateWithWeb3": [Function],
     "create": [Function],
     "createEmailLinkFlow": [Function],

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

@@ -8,7 +8,7 @@ import { useCardState } from '../../elements/contexts';
 import type { SocialButtonsProps } from '../../elements/SocialButtons';
 import { SocialButtons } from '../../elements/SocialButtons';
 import { useRouter } from '../../router';
-import { handleError, web3CallbackErrorHandler } from '../../utils';
+import { handleError, originPrefersPopup, web3CallbackErrorHandler } from '../../utils';
 
 export const SignInSocialButtons = React.memo((props: SocialButtonsProps) => {
   const clerk = useClerk();
@@ -19,11 +19,30 @@ export const SignInSocialButtons = React.memo((props: SocialButtonsProps) => {
   const signIn = useCoreSignIn();
   const redirectUrl = buildSSOCallbackURL(ctx, displayConfig.signInUrl);
   const redirectUrlComplete = ctx.afterSignInUrl || '/';
+  const shouldUsePopup = ctx.oauthFlow === 'popup' || (ctx.oauthFlow === 'auto' && originPrefersPopup());
 
   return (
     <SocialButtons
       {...props}
+      idleAfterDelay={!shouldUsePopup}
       oauthCallback={strategy => {
+        if (shouldUsePopup) {
+          // We create the popup window here with the `about:blank` URL since some browsers will block popups that are
+          // opened within async functions. The `signInWithPopup` method handles setting the URL of the popup.
+          const popup = window.open('about:blank', '', 'width=600,height=800');
+          // Unfortunately, there's no good way to detect when the popup is closed, so we simply poll and check if it's closed.
+          const interval = setInterval(() => {
+            if (!popup || popup.closed) {
+              clearInterval(interval);
+              card.setIdle();
+            }
+          }, 500);
+
+          return signIn
+            .authenticateWithPopup({ strategy, redirectUrl, redirectUrlComplete, popup })
+            .catch(err => handleError(err, [], card.setError));
+        }
+
         return signIn
           .authenticateWithRedirect({ strategy, redirectUrl, redirectUrlComplete })
           .catch(err => handleError(err, [], card.setError));

packages/clerk-js/src/ui/components/SignUp/SignUpSocialButtons.tsx

@@ -7,7 +7,7 @@ import { useCardState } from '../../elements';
 import type { SocialButtonsProps } from '../../elements/SocialButtons';
 import { SocialButtons } from '../../elements/SocialButtons';
 import { useRouter } from '../../router';
-import { handleError, web3CallbackErrorHandler } from '../../utils';
+import { handleError, originPrefersPopup, web3CallbackErrorHandler } from '../../utils';
 
 export type SignUpSocialButtonsProps = SocialButtonsProps & { continueSignUp?: boolean; legalAccepted?: boolean };
 
@@ -19,12 +19,39 @@ export const SignUpSocialButtons = React.memo((props: SignUpSocialButtonsProps)
   const signUp = useCoreSignUp();
   const redirectUrl = ctx.ssoCallbackUrl;
   const redirectUrlComplete = ctx.afterSignUpUrl || '/';
+  const shouldUsePopup = ctx.oauthFlow === 'popup' || (ctx.oauthFlow === 'auto' && originPrefersPopup());
   const { continueSignUp = false, ...rest } = props;
 
   return (
     <SocialButtons
       {...rest}
+      idleAfterDelay={!shouldUsePopup}
       oauthCallback={(strategy: OAuthStrategy) => {
+        if (shouldUsePopup) {
+          // We create the popup window here with the `about:blank` URL since some browsers will block popups that are
+          // opened within async functions. The `signUpWithPopup` method handles setting the URL of the popup.
+          const popup = window.open('about:blank', '', 'width=600,height=800');
+          // Unfortunately, there's no good way to detect when the popup is closed, so we simply poll and check if it's closed.
+          const interval = setInterval(() => {
+            if (!popup || popup.closed) {
+              clearInterval(interval);
+              card.setIdle();
+            }
+          }, 500);
+
+          return signUp
+            .authenticateWithPopup({
+              strategy,
+              redirectUrl,
+              redirectUrlComplete,
+              popup,
+              continueSignUp,
+              unsafeMetadata: ctx.unsafeMetadata,
+              legalAccepted: props.legalAccepted,
+            })
+            .catch(err => handleError(err, [], card.setError));
+        }
+
         return signUp
           .authenticateWithRedirect({
             continueSignUp,

packages/clerk-js/src/ui/contexts/components/SignIn.ts

@@ -129,6 +129,7 @@ export const useSignInContext = (): SignInContextType => {
   return {
     ...(ctx as SignInCtx),
     transferable: ctx.transferable ?? true,
+    oauthFlow: ctx.oauthFlow || 'auto',
     componentName,
     signUpUrl,
     signInUrl,