Add docs for enterprise_sso and update examples (#1770)

Co-authored-by: Alexis Aguilar <[email protected]>

docs/custom-flows/saml-connections.mdx → docs/custom-flows/enterprise-connections.mdx

@@ -1,25 +1,25 @@
 ---
-title: Build a custom flow for authenticating with SAML connections
-description: Learn how to use the Clerk API to build a custom sign-up and sign-in flow that supports OAuth connections.
+title: Build a custom flow for authenticating with enterprise connections
+description: Learn how to use the Clerk API to build a custom sign-up and sign-in flow that supports enterprise connections.
 ---
 
 <Include src="_partials/custom-flows-callout" />
 
 ## Before you start
 
-You must configure your application instance through the Clerk Dashboard for the SAML connection(s) that you want to use. Visit [the appropriate SAML guide for your platform](/docs/authentication/enterprise-connections/overview) to learn how to configure your instance.
+You must configure your application instance through the Clerk Dashboard for the enterprise connection(s) that you want to use. Visit [the appropriate guide for your platform](/docs/authentication/enterprise-connections/overview) to learn how to configure your instance.
 
 ## Create the sign-up and sign-in flow
 
-When using SAML, the sign-in and sign-up flows are equivalent. A successful SAML flow consists of the following steps:
+When using Enterprise SSO, the sign-in and sign-up flows are equivalent. A successful Enterprise SSO flow consists of the following steps:
 
-1. Start the SAML flow by calling [`SignIn.authenticateWithRedirect(params)`](/docs/references/javascript/sign-in/authenticate-with#authenticate-with-redirect) or [`SignUp.authenticateWithRedirect(params)`](/docs/references/javascript/sign-up/authenticate-with#authenticate-with-redirect). Both of these methods require a `redirectUrl` param, which is the URL that the browser will be redirected to once the user authenticates with the identity provider.
+1. Start the Enterprise SSO flow by calling [`SignIn.authenticateWithRedirect(params)`][sign-in-redirect] or [`SignUp.authenticateWithRedirect(params)`][sign-up-redirect]. Both of these methods require a `redirectUrl` param, which is the URL that the browser will be redirected to once the user authenticates with the identity provider.
 1. Create a route at the URL that the `redirectUrl` param points to. The following example names this route `/sso-callback`. This route should either call the [`Clerk.handleRedirectCallback()`](/docs/references/javascript/clerk/handle-navigation#handle-redirect-callback) method or render the prebuilt [`<AuthenticateWithRedirectCallback/>`](/docs/components/control/authenticate-with-callback) component.
 
 The following example shows two files:
 
-1. The sign-in page where the user can start the SAML flow.
-1. The SSO callback page where the SAML flow is completed.
+1. The sign-in page where the user can start the Enterprise SSO flow.
+1. The SSO callback page where the flow is completed.
 
 <Tabs items={["Next.js"]}>
   <Tab>
@@ -30,21 +30,21 @@ The following example shows two files:
       import * as React from 'react'
       import { useSignIn, useSignUp } from '@clerk/nextjs'
 
-      export default function SAMLSignIn() {
+      export default function Page() {
         const { signIn } = useSignIn()
         const { signUp } = useSignUp()
 
         if (!signIn || !signUp) return null
 
-        const signInWithSAML = (e: React.FormEvent) => {
+        const signInWithEnterpriseSSO = (e: React.FormEvent) => {
           e.preventDefault()
 
           const email = (e.target as HTMLFormElement).email.value
 
           signIn
             .authenticateWithRedirect({
               identifier: email,
-              strategy: 'saml',
+              strategy: 'enterprise_sso',
               redirectUrl: '/sso-callback',
               redirectUrlComplete: '/',
             })
@@ -58,9 +58,9 @@ The following example shows two files:
         }
 
         return (
-          <form onSubmit={(e) => signInWithSAML(e)}>
+          <form onSubmit={(e) => signInWithEnterpriseSSO(e)}>
             <input type="email" name="email" placeholder="Enter email address" />
-            <button>Sign in with SAML</button>
+            <button>Sign in with Enterprise SSO</button>
           </form>
         )
       }
@@ -69,24 +69,24 @@ The following example shows two files:
       ```jsx {{ filename: 'app/sign-up/sso-callback/page.tsx' }}
       import { AuthenticateWithRedirectCallback } from '@clerk/nextjs'
 
-      export default function SSOCallback() {
+      export default function Page() {
         // Handle the redirect flow by rendering the
         // prebuilt AuthenticateWithRedirectCallback component.
-        // This is the final step in the custom SAML flow.
+        // This is the final step in the custom Enterprise SSO flow.
         return <AuthenticateWithRedirectCallback />
       }
       ```
     </CodeBlockTabs>
   </Tab>
 </Tabs>
 
-## SAML account transfer flows
+## Enterprise account transfer flows
 
-It is common for users who are authenticating with SAML to use a sign-in button when they mean to sign-up, and vice versa. For those cases, the `SignIn` and `SignUp` objects have a `transferable` status that indicates whether the user can be transferred to the other flow.
+It is common for users who are authenticating with an enterprise account to use a sign-in button when they mean to sign-up, and vice versa. For those cases, the `SignIn` and `SignUp` objects have a `transferable` status that indicates whether the user can be transferred to the other flow.
 
 **If you would like to keep your sign-in and sign-up flows completely separate, then you can skip this section.**
 
-The following example demonstrates how to handle these cases in your sign-in flow. To apply the same logic to the sign-up flow, simply replace `signIn.authenticateWithRedirect()` with `signUp.authenticateWithRedirect()` in your code.
+The following example demonstrates how to handle these cases in your sign-in flow. To apply the same logic to the sign-up flow, simply replace [`signIn.authenticateWithRedirect()`][sign-in-redirect] with [`signUp.authenticateWithRedirect()`][sign-up-redirect] in your code.
 
 <Tabs items={["Next.js"]}>
   <Tab>
@@ -96,21 +96,21 @@ The following example demonstrates how to handle these cases in your sign-in flo
     import * as React from 'react'
     import { useSignIn, useSignUp } from '@clerk/nextjs'
 
-    export default function SAMLSignIn() {
+    export default function Page() {
       const { signIn } = useSignIn()
       const { signUp, setActive } = useSignUp()
 
       if (!signIn || !signUp) return null
 
-      const signInWithSAML = (e: React.FormEvent) => {
+      const signInWithEnterpriseSSO = (e: React.FormEvent) => {
         e.preventDefault()
 
         const email = (e.target as HTMLFormElement).email.value
 
         signIn
           .authenticateWithRedirect({
             identifier: email,
-            strategy: 'saml',
+            strategy: 'enterprise_sso',
             redirectUrl: '/sso-callback',
             redirectUrlComplete: '/',
           })
@@ -127,7 +127,7 @@ The following example demonstrates how to handle these cases in your sign-in flo
         if (!signIn || !signUp) return null
 
         // If the user has an account in your application, but does not yet
-        // have a SAML account connected to it, you can transfer the SAML
+        // have a enterprise account connected to it, you can transfer the enterprise
         // account to the existing user account.
         const userExistsButNeedsToSignIn =
           signUp.verifications.externalAccount.status === 'transferable' &&
@@ -143,9 +143,9 @@ The following example demonstrates how to handle these cases in your sign-in flo
           }
         }
 
-        // If the user has a SAML account but does not yet
+        // If the user has a enterprise account but does not yet
         // have an account in your app, you can create an account
-        // for them using the SAML information.
+        // for them using the enterprise account's information.
         const userNeedsToBeCreated = signIn.firstFactorVerification.status === 'transferable'
 
         if (userNeedsToBeCreated) {
@@ -160,18 +160,22 @@ The following example demonstrates how to handle these cases in your sign-in flo
           }
         } else {
           // If the user has an account in your application
-          // and has an SAML account connected to it, you can sign them in.
-          signInWithSAML(e)
+          // and has an enterprise account connected to it, you can sign them in.
+          signInWithEnterpriseSSO(e)
         }
       }
 
       return (
         <form onSubmit={(e) => handleSignIn(e)}>
           <input type="email" name="email" placeholder="Enter email address" />
-          <button>Sign in with SAML</button>
+          <button>Sign in with Enterprise SSO</button>
         </form>
       )
     }
     ```
   </Tab>
 </Tabs>
+
+[sign-in-redirect]: /docs/references/javascript/sign-in/authenticate-with#authenticate-with-redirect
+
+[sign-up-redirect]: /docs/references/javascript/sign-up/authenticate-with#authenticate-with-redirect

docs/manifest.json

@@ -1673,8 +1673,8 @@
                           "href": "/docs/custom-flows/oauth-connections"
                         },
                         {
-                          "title": "SAML connections",
-                          "href": "/docs/custom-flows/saml-connections"
+                          "title": "Enterprise connections",
+                          "href": "/docs/custom-flows/enterprise-connections"
                         },
                         {
                           "title": "Sign out",

docs/references/javascript/sign-in/authenticate-with.mdx

@@ -19,23 +19,34 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi
 
 <Properties>
   - `strategy`
-  - <code>[OAuthStrategy](/docs/references/javascript/types/oauth#o-auth-strategy) | 'saml'</code>
+  - <code>[OAuthStrategy](/docs/references/javascript/types/oauth#o-auth-strategy) | 'saml' | 'enterprise\_sso'</code>
 
-  The strategy corresponding to the OAuth provider. For example: `oauth_facebook`, `oauth_github`, etc.
+  The strategy to use for authentication. The following strategies are supported:
+
+  - `oauth_<provider>`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider).
+  - `saml`: The user will be authenticated with SAML. **Deprecated in favor of `enterprise_sso`.**
+  - `enterprise_sso`: The user will be authenticated either through SAML or OIDC, depending on the configuration of the [enterprise connection](/docs/authentication/enterprise-connections/overview) matching the identifier.
 
   ---
 
   - `redirectUrl`
   - `string`
 
-  Full URL or path to the route that will complete the OAuth or SAML flow. Typically, this will be a simple `/sso-callback` route that calls `Clerk.handleRedirectCallback` or mounts the `<AuthenticateWithRedirectCallback />` component.
+  The full URL or path to the route that will complete the OAuth or SAML flow. Typically, this will be a simple `/sso-callback` route that calls `Clerk.handleRedirectCallback` or mounts the `<AuthenticateWithRedirectCallback />` component.
 
   ---
 
   - `redirectUrlComplete`
   - `string`
 
   The URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign in.
+
+  ---
+
+  - `identifier`
+  - `string | undefined`
+
+  Identifier to use for targeting an enterprise connection at sign-in.
 </Properties>
 
 ### `authenticateWithMetamask()`

docs/references/javascript/sign-up/authenticate-with.mdx

@@ -38,26 +38,27 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi
   ---
 
   - `strategy`
-  - `'oauth_<provider>' | 'saml'`
+  - `'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 sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider).
-  - `saml`: The user will be authenticated with SAML.
+  - `saml`: The user will be authenticated with SAML. **Deprecated**
+  - `enterprise_sso`: The user will be authenticated either through SAML or OIDC, depending on the configuration of the [enterprise connection](/docs/authentication/enterprise-connections/overview) matching the identifier.
 
   ---
 
   - `identifier`
   - `string | undefined`
 
-  Identifier to use for targeting a SAML connection at sign-up.
+  Identifier to use for targeting an enterprise connection at sign-up.
 
   ---
 
   - `emailAddress`
   - `string | undefined`
 
-  Email address to use for targeting a SAML connection at sign-up.
+  Email address to use for targeting an enterprise connection at sign-up.
 
   ---
 

docs/references/javascript/sign-up/verification.mdx

@@ -20,14 +20,15 @@ function prepareVerification(params: PrepareVerificationParams): Promise<SignUpR
 
 <Properties>
   - `strategy`
-  - `'phone_code' | 'email_code' | 'email_link' | 'saml' | 'oauth_<provider>' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature'`
+  - `'phone_code' | 'email_code' | 'email_link' | 'saml' | 'enterprise_sso' | 'oauth_<provider>' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature'`
 
   The verification strategy to validate the user's sign-up request. The following strategies are supported:
 
   - `phone_code`: Send an SMS with a unique token to input.
   - `email_code`: Send an email with a unique token to input.
   - `email_link`: Send an email with a link which validates sign-up
-  - `saml`: The user will be authenticated with SAML. **Experimental**
+  - `saml`: The user will be authenticated with SAML. **Deprecated in favor of `enterprise_sso`.**
+  - `enterprise_sso`: The user will be authenticated either through SAML or OIDC depending on the configuration of the [enterprise connection](/docs/authentication/enterprise-connections/overview) matching the identifier.
   - `oauth_<provider>`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider).
   - `web3_metamask_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Metamask](https://metamask.io/). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used.
   - `web3_coinbase_wallet_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Coinbase Wallet](https://www.coinbase.com/wallet). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used.

docs/references/javascript/types/verification.mdx

@@ -48,7 +48,7 @@ An interface that represents the state of the verification process of a sign-in
 
   - `unverified`: The verification has not been verified yet.
   - `verified`: The verification has been verified.
-  - `transferable`: The verification is transferable to between sign-in and sign-up flows. This status is to be used in [OAuth](/docs/custom-flows/oauth-connections#o-auth-account-transfer-flows) and [SAML](/docs/custom-flows/saml-connections#saml-account-transfer-flows) authentication flows.
+  - `transferable`: The verification is transferable to between sign-in and sign-up flows. This status is to be used in [OAuth](/docs/custom-flows/oauth-connections#o-auth-account-transfer-flows) and [Enterprise SSO](/docs/custom-flows/enterprise-connections#enterprise-account-transfer-flows) authentication flows.
   - `failed`: The verification has failed.
   - `expired`: The verification has expired.