feat: add docs for authenticateWithPopup (#2188)

dstaley · alexisintech · web-flow · commit e3a9d04bb406 · 2025-04-16T09:39:00.000-07:00
Co-authored-by: Alexis Aguilar &lt;98043211+alexisintech@users.noreply.github.com&gt;
diff --git a/docs/components/authentication/sign-in.mdx b/docs/components/authentication/sign-in.mdx
@@ -50,6 +50,19 @@ All props are optional.
 
   ---
 
+  - `oauthFlow`
+  - `"redirect" | "popup" | "auto"`
+
+  Determines how OAuth authentication is performed. Accepts the following properties:
+
+  - `"redirect"`: Redirect to the OAuth provider on the current page.
+  - `"popup"`: Open a popup window.
+  - `"auto"`: Choose the best method based on whether the current domain typically requires the `"popup"` flow to correctly perform authentication.
+
+  Defaults to `"auto"`.
+
+  ---
+
   - `path`
   - `string`
 
diff --git a/docs/components/authentication/sign-up.mdx b/docs/components/authentication/sign-up.mdx
@@ -50,6 +50,19 @@ All props are optional.
 
   ---
 
+  - `oauthFlow`
+  - `"redirect" | "popup" | "auto"`
+
+  Determines how OAuth authentication is performed. Accepts the following properties:
+
+  - `"redirect"`: Redirect to the OAuth provider on the current page.
+  - `"popup"`: Open a popup window.
+  - `"auto"`: Choose the best method based on whether the current domain typically requires the `"popup"` flow to correctly perform authentication.
+
+  Defaults to `"auto"`.
+
+  ---
+
   - `path`
   - `string`
 
diff --git a/docs/components/unstyled/sign-in-button.mdx b/docs/components/unstyled/sign-in-button.mdx
@@ -29,6 +29,19 @@ The `<SignInButton>` component is a button that links to the sign-in page or dis
 
   ---
 
+  - `oauthFlow`
+  - `"redirect" | "popup" | "auto"`
+
+  Determines how OAuth authentication is performed. Accepts the following properties:
+
+  - `"redirect"`: Redirect to the OAuth provider on the current page.
+  - `"popup"`: Open a popup window.
+  - `"auto"`: Choose the best method based on whether the current domain typically requires the `"popup"` flow to correctly perform authentication.
+
+  Defaults to `"auto"`.
+
+  ---
+
   - `signUpForceRedirectUrl?`
   - `string`
 
diff --git a/docs/components/unstyled/sign-up-button.mdx b/docs/components/unstyled/sign-up-button.mdx
@@ -29,6 +29,19 @@ The `<SignUpButton>` component is a button that links to the sign-up page or dis
 
   ---
 
+  - `oauthFlow`
+  - `"redirect" | "popup" | "auto"`
+
+  Determines how OAuth authentication is performed. Accepts the following properties:
+
+  - `"redirect"`: Redirect to the OAuth provider on the current page.
+  - `"popup"`: Open a popup window.
+  - `"auto"`: Choose the best method based on whether the current domain typically requires the `"popup"` flow to correctly perform authentication.
+
+  Defaults to `"auto"`.
+
+  ---
+
   - `signInForceRedirectUrl?`
   - `string`
 
diff --git a/docs/references/javascript/sign-in.mdx b/docs/references/javascript/sign-in.mdx
@@ -332,6 +332,76 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi
 For OAuth connections, see the [custom flow for OAuth connections](/docs/custom-flows/oauth-connections).
 For enterprise connections, see the [custom flow for enterprise connections](/docs/custom-flows/enterprise-connections).
 
+### `authenticateWithPopup()`
+
+Opens a popup window to allow a user to sign in via a Single Sign On (SSO) connection, such as OAuth or SAML, where an external account is used for verifying the user's identity.
+
+```typescript
+function authenticateWithPopup(params: AuthenticateWithPopupParams): Promise<void>
+```
+
+#### `AuthenticateWithPopupParams`
+
+<Properties>
+  - `continueSignUp?`
+  - `boolean | undefined`
+
+  Whether to continue (i.e. PATCH) an existing `SignUp` (if present) or create a new `SignUp`.
+
+  ---
+
+  - `emailAddress?`
+  - `string | undefined`
+
+  The email address used to target an enterprise connection during sign-in.
+
+  ---
+
+  - `identifier?`
+  - `string | undefined`
+
+    The ID used to target an enterprise connection during sign-in.
+
+  ---
+
+  - `legalAccepted?`
+  - `boolean | undefined`
+
+  A boolean indicating whether the user has agreed to the [legal compliance](/docs/authentication/configuration/legal-compliance) documents.
+
+  ---
+
+  - `popup?`
+  - `Window | null`
+
+  A reference to a popup window opened via `window.open()`.
+
+  ---
+
+  - `redirectUrl`
+  - `string`
+
+  The full URL or path that the OAuth provider should redirect to after successful authorization on their part. Typically, this will be a simple `/sso-callback` route that calls [`Clerk.handleRedirectCallback`](/docs/references/javascript/clerk#handle-redirect-callback) or mounts the [`<AuthenticateWithRedirectCallback />`](/docs/components/control/authenticate-with-callback) component. See the [custom flow](/docs/custom-flows/oauth-connections) for implementation details.
+
+  ---
+
+  - `redirectUrlComplete`
+  - `string`
+
+  The full URL or path that the user will be redirected to once the sign-in is complete.
+
+  ---
+
+  - `strategy`
+  - <code>[OAuthStrategy](/docs/references/javascript/types/sso#o-auth-strategy) | 'saml' | 'enterprise\_sso'</code>
+
+  The strategy to use for authentication. The following strategies are supported:
+
+  - `'oauth_<provider>'`: The user will be authenticated with their [social connection account](/docs/authentication/social-connections/oauth). See a list of [supported values for `<provider>`](/docs/references/javascript/types/sso).
+  - `'saml'` (deprecated): **Deprecated in favor of `'enterprise_sso'`.** The user will be authenticated with their [SAML account](/docs/authentication/enterprise-connections/overview#saml).
+  - `'enterprise_sso'`: The user will be authenticated either through SAML or OIDC depending on the configuration of their [enterprise SSO account](/docs/authentication/enterprise-connections/overview).
+</Properties>
+
 ### `authenticateWithWeb3()`
 
 Initiates a Web3 authentication flow by verifying the user's ownership of a blockchain wallet address through cryptographic signature verification. This method enables decentralized authentication without requiring traditional credentials.
diff --git a/docs/references/javascript/sign-up.mdx b/docs/references/javascript/sign-up.mdx
@@ -331,7 +331,7 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi
   - `continueSignUp`
   - `boolean | undefined`
 
-  Whether to continue (i.e. PATCH) an existing \[`SignUp`]\[signup-ref] (if present) or create a new \[`SignUp`]\[signup-ref].
+  Whether to continue (i.e. PATCH) an existing `SignUp` (if present) or create a new `SignUp`.
 
   ---
 
@@ -371,6 +371,81 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi
 For OAuth connections, see the [custom flow for OAuth connections](/docs/custom-flows/oauth-connections).
 For enterprise connections, see the [custom flow for enterprise connections](/docs/custom-flows/enterprise-connections).
 
+### `authenticateWithPopup()`
+
+Opens a popup window to allow a user to sign up via a Single Sign On (SSO) connection, such as OAuth or SAML, where an external account is used for verifying the user's identity.
+
+```typescript
+function authenticateWithPopup(params: AuthenticateWithPopupParams): Promise<void>
+```
+
+#### `AuthenticateWithPopupParams`
+
+<Properties>
+  - `redirectUrl`
+  - `string`
+
+  The full URL or path that the OAuth provider should redirect to after successful authorization on their part. Typically, this will be a simple `/sso-callback` route that either calls [`Clerk.handleRedirectCallback`](/docs/references/javascript/clerk#handle-redirect-callback) or mounts the [`<AuthenticateWithRedirectCallback />`](/docs/components/control/authenticate-with-callback) component. See the [custom flow](/docs/custom-flows/oauth-connections) for implementation details.
+
+  ---
+
+  - `redirectUrlComplete`
+  - `string`
+
+  The full URL or path to navigate to after the OAuth or SAML flow completes.
+
+  ---
+
+  - `strategy`
+  - `'oauth_<provider>' | 'saml' | 'enterprise_sso'`
+
+  The strategy to use for authentication. The following strategies are supported:
+
+  - `'oauth_<provider>'`: The user will be authenticated with their [social connection account](/docs/authentication/social-connections/oauth). See a list of [supported values for `<provider>`](/docs/references/javascript/types/sso).
+  - `'saml'` (deprecated): **Deprecated in favor of `'enterprise_sso'`.** The user will be authenticated with their [SAML account](/docs/authentication/enterprise-connections/overview#saml).
+  - `'enterprise_sso'`: The user will be authenticated either through SAML or OIDC depending on the configuration of their [enterprise SSO account](/docs/authentication/enterprise-connections/overview).
+
+  ---
+
+  - `continueSignUp?`
+  - `boolean | undefined`
+
+  Whether to continue (i.e. PATCH) an existing `SignUp` (if present) or create a new `SignUp`.
+
+  ---
+
+  - `emailAddress?`
+  - `string | undefined`
+
+  Email address to use for targeting an enterprise connection at sign-up.
+
+  ---
+
+  - `identifier?`
+  - `string | undefined`
+
+  Identifier to use for targeting an enterprise connection at sign-up.
+
+  ---
+
+  - `legalAccepted?`
+  - `boolean`
+
+  A boolean indicating whether the user has agreed to the [legal compliance](/docs/authentication/configuration/legal-compliance) documents.
+
+  ---
+
+  - `popup?`
+  - `Window`
+
+  A reference to a popup window opened via `window.open()`.
+</Properties>
+
+#### Example
+
+For OAuth connections, see the [custom flow for OAuth connections](/docs/custom-flows/oauth-connections).
+For enterprise connections, see the [custom flow for enterprise connections](/docs/custom-flows/enterprise-connections).
+
 ### `authenticateWithWeb3()`
 
 Initiates a Web3 authentication flow by verifying the user's ownership of a blockchain wallet address through cryptographic signature verification. This method enables decentralized authentication without requiring traditional credentials.
