feat(clerk-expo): Deprecate useOAuth and introduce docs for useSSO

docs/_partials/custom-flows/sso-connections.mdx

@@ -0,0 +1,12 @@
+The following example **will both sign up _and_ sign in users**, eliminating the need for a separate sign-up page. However, if you want to have separate sign-up and sign-in pages, the sign-up and sign-in flows are equivalent, meaning that all you have to do is swap out the `SignIn` object for the `SignUp` object using the [`useSignUp()`](/docs/references/react/use-sign-up) hook.
+
+The following example:
+
+1. Accesses the [`SignIn`](/docs/references/javascript/sign-in/sign-in) object using the [`useSignIn()`](/docs/references/react/use-sign-in) hook.
+1. Starts the authentication process by calling [`SignIn.authenticateWithRedirect(params)`](/docs/references/javascript/sign-in/authenticate-with#authenticate-with-redirect). This method requires a `redirectUrl` param, which is the URL that the browser will be redirected to once the user authenticates with the identity provider.
+1. Creates a route at the URL that the `redirectUrl` param points to. The following example names this route `/sso-callback`. This route should either render the prebuilt [`<AuthenticateWithRedirectCallback/>`](/docs/components/control/authenticate-with-callback) component or call the [`Clerk.handleRedirectCallback()`](/docs/references/javascript/clerk/handle-navigation#handle-redirect-callback) method if you're not using the prebuilt component.
+
+The following example shows two files:
+
+1. The sign-in page where the user can start the authentication flow.
+1. The SSO callback page where the flow is completed.

docs/_partials/expo/enterprise-sso-custom-flow.mdx

@@ -0,0 +1,78 @@
+> [!IMPORTANT]
+> Expo supports [SAML](/docs/authentication/enterprise-connections/overview#saml) Enterprise SSO, but does not support [OIDC](/docs/authentication/enterprise-connections/overview#oidc).
+
+The following example **will both sign up _and_ sign in users**, eliminating the need for a separate sign-up page.
+
+The following example:
+
+1. Accesses the `startSSOFlow()` method using the [`useSSO()`](/docs/references/expo/use-sso) hook.
+1. Calls the `startSSOFlow()` method with the `strategy` param set to `enterprise_sso` and the `identifier` param set to the user's email address that they provided.
+   - If authentication is successful, the `setActive()` method is called to set the active session with the new `createdSessionId`.
+   - If authentication is not successful, you can handle the missing requirements, such as MFA, using the [`signIn`](/docs/references/javascript/sign-in/sign-in) or [`signUp`](/docs/references/javascript/sign-up/sign-up) object returned from `startSSOFlow()`, depending on if the user is signing in or signing up. These objects include properties, like `status`, that can be used to determine the next steps. See the respective linked references for more information.
+
+```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }}
+import React, { useEffect, useState } from 'react'
+import * as WebBrowser from 'expo-web-browser'
+import { useSSO } from '@clerk/clerk-expo'
+import { View, Button, TextInput } from 'react-native'
+
+export const useWarmUpBrowser = () => {
+  useEffect(() => {
+    // Preloads the browser for Android devices to reduce authentication load time
+    // See: https://docs.expo.dev/guides/authentication/#improving-user-experience
+    void WebBrowser.warmUpAsync()
+    return () => {
+      // Cleanup: closes browser when component unmounts
+      void WebBrowser.coolDownAsync()
+    }
+  }, [])
+}
+
+// Handle any pending authentication sessions
+WebBrowser.maybeCompleteAuthSession()
+
+export default function Page() {
+  useWarmUpBrowser()
+
+  const [email, setEmail] = useState('')
+
+  // Use the `useSSO()` hook to access the `startSSOFlow()` method
+  const { startSSOFlow } = useSSO()
+
+  const onPress = async () => {
+    try {
+      // Start the authentication process by calling `startSSOFlow()`
+      const { createdSessionId, setActive, signIn, signUp } = await startSSOFlow({
+        strategy: 'enterprise_sso',
+        identifier: email,
+      })
+
+      // If sign in was successful, set the active session
+      if (createdSessionId) {
+        setActive!({ session: createdSessionId })
+      } else {
+        // If there is no `createdSessionId`,
+        // there are missing requirements, such as MFA
+        // Use the `signIn` or `signUp` returned from `startSSOFlow`
+        // to handle next steps
+      }
+    } catch (err) {
+      // See https://clerk.com/docs/custom-flows/error-handling
+      // for more info on error handling
+      console.error(JSON.stringify(err, null, 2))
+    }
+  }
+
+  return (
+    <View>
+      <TextInput
+        value={email}
+        onChangeText={setEmail}
+        placeholder="Enter email"
+        placeholderTextColor="#666666"
+      />
+      <Button title="Sign in with SAML" onPress={onPress} />
+    </View>
+  )
+}
+```

docs/_partials/expo/oauth-custom-flow.mdx

@@ -1,58 +1,67 @@
-The following example demonstrates how to create a custom OAuth sign-in flow for [Google accounts](/docs/authentication/social-connections/google).
+The following example **will both sign up _and_ sign in users**, eliminating the need for a separate sign-up page.
+
+The following example:
+
+1. Accesses the `startSSOFlow()` method using the [`useSSO()`](/docs/references/expo/use-sso) hook.
+1. Calls the `startSSOFlow()` method with the `strategy` param set to `oauth_google`, but you can use any of the [supported OAuth strategies](/docs/references/javascript/types/sso#oauth-strategy).
+   - If authentication is successful, the `setActive()` method is called to set the active session with the new `createdSessionId`.
+   - If authentication is not successful, you can handle the missing requirements, such as MFA, using the [`signIn`](/docs/references/javascript/sign-in/sign-in) or [`signUp`](/docs/references/javascript/sign-up/sign-up) object returned from `startSSOFlow()`, depending on if the user is signing in or signing up. These objects include properties, like `status`, that can be used to determine the next steps. See the respective linked references for more information.
 
 ```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }}
-import React from 'react'
-import * as WebBrowser from 'expo-web-browser'
-import { Text, View, Button } from 'react-native'
-import { Link } from 'expo-router'
-import { useOAuth } from '@clerk/clerk-expo'
-import * as Linking from 'expo-linking'
+import React, { useCallback, useEffect } from "react";
+import * as WebBrowser from "expo-web-browser";
+import { useSSO } from "@clerk/clerk-expo";
+import { View, Button } from "react-native";
 
 export const useWarmUpBrowser = () => {
-  React.useEffect(() => {
-    // Warm up the android browser to improve UX
-    // https://docs.expo.dev/guides/authentication/#improving-user-experience
-    void WebBrowser.warmUpAsync()
+  useEffect(() => {
+    // Preloads the browser for Android devices to reduce authentication load time
+    // See: https://docs.expo.dev/guides/authentication/#improving-user-experience
+    void WebBrowser.warmUpAsync();
     return () => {
-      void WebBrowser.coolDownAsync()
-    }
-  }, [])
-}
+      // Cleanup: closes browser when component unmounts
+      void WebBrowser.coolDownAsync();
+    };
+  }, []);
+};
 
-WebBrowser.maybeCompleteAuthSession()
+// Handle any pending authentication sessions
+WebBrowser.maybeCompleteAuthSession();
 
 export default function Page() {
-  useWarmUpBrowser()
+  useWarmUpBrowser();
 
-  const { startOAuthFlow } = useOAuth({ strategy: 'oauth_google' })
+  // Use the `useSSO()` hook to access the `startSSOFlow()` method
+  const { startSSOFlow } = useSSO();
 
-  const onPress = React.useCallback(async () => {
+  const onPress = useCallback(async () => {
     try {
-      const { createdSessionId, signIn, signUp, setActive } = await startOAuthFlow({
-        redirectUrl: Linking.createURL('/dashboard', { scheme: 'myapp' }),
-      })
+      // Start the authentication process by calling `startSSOFlow()`
+      const { createdSessionId, setActive, signIn, signUp } =
+        await startSSOFlow({
+          strategy: "oauth_google",
+        });
 
       // If sign in was successful, set the active session
       if (createdSessionId) {
-        setActive!({ session: createdSessionId })
+        setActive!({ session: createdSessionId });
       } else {
-        // Use signIn or signUp returned from startOAuthFlow
-        // for next steps, such as MFA
+        // If there is no `createdSessionId`,
+        // there are missing requirements, such as MFA
+        // Use the `signIn` or `signUp` returned from `startSSOFlow`
+        // to handle next steps
       }
     } catch (err) {
       // See https://clerk.com/docs/custom-flows/error-handling
       // for more info on error handling
-      console.error(JSON.stringify(err, null, 2))
+      console.error(JSON.stringify(err, null, 2));
     }
-  }, [])
+  }, []);
 
   return (
     <View>
-      <Link href="/">
-        <Text>Home</Text>
-      </Link>
       <Button title="Sign in with Google" onPress={onPress} />
     </View>
-  )
+  );
 }
 ```

docs/custom-flows/enterprise-connections.mdx

@@ -11,171 +11,68 @@ You must configure your application instance through the Clerk Dashboard for the
 
 ## Create the sign-up and sign-in flow
 
-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 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 Enterprise SSO flow.
-1. The SSO callback page where the flow is completed.
-
-<Tabs items={["Next.js"]}>
+<Tabs items={["Next.js", "Expo"]}>
   <Tab>
+    <Include src="_partials/custom-flows/sso-connections" />
+
     <CodeBlockTabs options={["Sign in page", "SSO callback page"]}>
       ```tsx {{ filename: 'app/sign-in/page.tsx' }}
       'use client'
 
       import * as React from 'react'
-      import { useSignIn, useSignUp } from '@clerk/nextjs'
+      import { useSignIn } from '@clerk/nextjs'
 
       export default function Page() {
-        const { signIn } = useSignIn()
-        const { signUp } = useSignUp()
-
-        if (!signIn || !signUp) return null
+        const { signIn, isLoaded } = useSignIn()
 
         const signInWithEnterpriseSSO = (e: React.FormEvent) => {
           e.preventDefault()
 
+          if (!isLoaded) return null
+
           const email = (e.target as HTMLFormElement).email.value
 
           signIn
             .authenticateWithRedirect({
               identifier: email,
               strategy: 'enterprise_sso',
-              redirectUrl: '/sign-up/sso-callback',
+              redirectUrl: '/sign-in/sso-callback',
               redirectUrlComplete: '/',
             })
             .then((res) => {
               console.log(res)
             })
             .catch((err: any) => {
+              // See https://clerk.com/docs/custom-flows/error-handling
+              // for more info on error handling
               console.log(err.errors)
               console.error(err, null, 2)
             })
         }
 
         return (
           <form onSubmit={(e) => signInWithEnterpriseSSO(e)}>
-            <input type="email" name="email" placeholder="Enter email address" />
+            <input id="email" type="email" name="email" placeholder="Enter email address" />
             <button>Sign in with Enterprise SSO</button>
           </form>
         )
       }
       ```
 
-      ```jsx {{ filename: 'app/sign-up/sso-callback/page.tsx' }}
+      ```jsx {{ filename: 'app/sign-in/sso-callback/page.tsx' }}
       import { AuthenticateWithRedirectCallback } from '@clerk/nextjs'
 
       export default function Page() {
-        // Handle the redirect flow by rendering the
-        // prebuilt AuthenticateWithRedirectCallback component.
+        // Handle the redirect flow by calling the Clerk.handleRedirectCallback() method
+        // or rendering the prebuilt <AuthenticateWithRedirectCallback/> component.
         // This is the final step in the custom Enterprise SSO flow.
         return <AuthenticateWithRedirectCallback />
       }
       ```
     </CodeBlockTabs>
   </Tab>
-</Tabs>
-
-## Enterprise account transfer flows
-
-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()`][sign-in-redirect] with [`signUp.authenticateWithRedirect()`][sign-up-redirect] in your code.
-
-<Tabs items={["Next.js"]}>
   <Tab>
-    ```tsx {{ filename: 'app/sign-in/[[...sign-in]]/page.tsx', collapsible: true }}
-    'use client'
-
-    import * as React from 'react'
-    import { useSignIn, useSignUp } from '@clerk/nextjs'
-
-    export default function Page() {
-      const { signIn } = useSignIn()
-      const { signUp, setActive } = useSignUp()
-
-      if (!signIn || !signUp) return null
-
-      const signInWithEnterpriseSSO = (e: React.FormEvent) => {
-        e.preventDefault()
-
-        const email = (e.target as HTMLFormElement).email.value
-
-        signIn
-          .authenticateWithRedirect({
-            identifier: email,
-            strategy: 'enterprise_sso',
-            redirectUrl: '/sign-up/sso-callback',
-            redirectUrlComplete: '/',
-          })
-          .then((res) => {
-            console.log(res)
-          })
-          .catch((err: any) => {
-            console.log(err.errors)
-            console.error(err, null, 2)
-          })
-      }
-
-      async function handleSignIn(e: React.FormEvent) {
-        if (!signIn || !signUp) return null
-
-        // If the user has an account in your application, but does not yet
-        // 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' &&
-          signUp.verifications.externalAccount.error?.code === 'external_account_exists'
-
-        if (userExistsButNeedsToSignIn) {
-          const res = await signIn.create({ transfer: true })
-
-          if (res.status === 'complete') {
-            setActive({
-              session: res.createdSessionId,
-            })
-          }
-        }
-
-        // 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 enterprise account's information.
-        const userNeedsToBeCreated = signIn.firstFactorVerification.status === 'transferable'
-
-        if (userNeedsToBeCreated) {
-          const res = await signUp.create({
-            transfer: true,
-          })
-
-          if (res.status === 'complete') {
-            setActive({
-              session: res.createdSessionId,
-            })
-          }
-        } else {
-          // If the user has an account in your application
-          // 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 Enterprise SSO</button>
-        </form>
-      )
-    }
-    ```
+    <Include src="_partials/expo/enterprise-sso-custom-flow" />
   </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