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

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

@@ -0,0 +1,58 @@
+The following example demonstrates how to create a custom OAuth sign-in flow for [Google accounts](/docs/authentication/social-connections/google).
+
+```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'
+
+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()
+    return () => {
+      void WebBrowser.coolDownAsync()
+    }
+  }, [])
+}
+
+WebBrowser.maybeCompleteAuthSession()
+
+export default function Page() {
+  useWarmUpBrowser()
+
+  const { startOAuthFlow } = useOAuth({ strategy: 'oauth_google' })
+
+  const onPress = React.useCallback(async () => {
+    try {
+      const { createdSessionId, signIn, signUp, setActive } = await startOAuthFlow({
+        redirectUrl: Linking.createURL('/dashboard', { scheme: 'myapp' }),
+      })
+
+      // If sign in was successful, set the active session
+      if (createdSessionId) {
+        setActive!({ session: createdSessionId })
+      } else {
+        // Use signIn or signUp returned from startOAuthFlow
+        // for next steps, such as MFA
+      }
+    } 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>
+      <Link href="/">
+        <Text>Home</Text>
+      </Link>
+      <Button title="Sign in with Google" onPress={onPress} />
+    </View>
+  )
+}
+```

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

@@ -0,0 +1,58 @@
+The following example demonstrates how to create a custom SSO flow with [SAML](docs/authentication/enterprise-connections/overview#saml).
+
+```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }}
+import React, { useCallback, useEffect } from 'react'
+import * as WebBrowser from 'expo-web-browser'
+import * as Linking from 'expo-linking'
+import { useSSO } from '@clerk/clerk-expo'
+import { View, Button } 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 { startSSOFlow } = useSSO()
+
+  const onPress = useCallback(async () => {
+    try {
+      const { createdSessionId, setActive, signIn, signUp } = await startSSOFlow({
+        strategy: 'enterprise_sso',
+        // This identifier would likely be derived from a text input
+        identifier: '[email protected]',
+      })
+
+      // If sign in was successful, set the active session
+      if (createdSessionId) {
+        setActive!({ session: createdSessionId })
+      } else {
+        // Use `signIn` or `signUp` returned from `startSSOFlow`
+        // for next steps, such as MFA
+      }
+    } 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>
+      <Button title="Sign in with SSO" onPress={onPress} />
+    </View>
+  )
+}
+```

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

@@ -1,42 +1,43 @@
-The following example demonstrates how to create a custom OAuth sign-in flow for [Google accounts](/docs/authentication/social-connections/google).
+The following example demonstrates how to create a custom SSO flow for [Google OAuth](/docs/authentication/social-connections/google).
 
 ```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }}
-import React from 'react'
+import React, { useCallback, useEffect } 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 { 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
+  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 { startOAuthFlow } = useOAuth({ strategy: 'oauth_google' })
+  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' }),
+      const { createdSessionId, setActive, signIn, signUp } = await startSSOFlow({
+        strategy: 'oauth_google',
       })
 
       // If sign in was successful, set the active session
       if (createdSessionId) {
         setActive!({ session: createdSessionId })
       } else {
-        // Use signIn or signUp returned from startOAuthFlow
+        // Use `signIn` or `signUp` returned from `startSSOFlow`
         // for next steps, such as MFA
       }
     } catch (err) {
@@ -48,9 +49,6 @@ export default function Page() {
 
   return (
     <View>
-      <Link href="/">
-        <Text>Home</Text>
-      </Link>
       <Button title="Sign in with Google" onPress={onPress} />
     </View>
   )

docs/deployments/deploy-expo.mdx

@@ -15,23 +15,11 @@ With Clerk, you can [add OAuth flows in your Expo applications](/docs/custom-flo
 
 Clerk ensures that security critical nonces will be passed only to allowlisted URLs when the OAuth flow is complete in native browsers or webviews.
 
-So for maximum security in your production instances, you need to allowlist your custom redirect URLs:
+So for maximum security in your production instances, you need to allowlist the SSO callback URL:
 
 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
-1. Scroll to the **Allowlist for mobile OAuth redirect** section and add your redirect URLs.
-   1. The default is `<INSERT-YOUR-APP-SCHEME>://oauth-native-callback`
-   1. If you'd like to pass a custom redirect URL, make sure you add that to the allowlist. The format is `<INSERT-YOUR-APP-SCHEME>/{PATH}`. For example, the redirect URL for the following code example is `myapp://dashboard`.
-      ```ts
-      const { startOAuthFlow } = useOAuth({ strategy: `oauth_apple` })
-
-      const onPress = React.useCallback(async () => {
-        const { createdSessionId, setActive } = await startOAuthFlow({
-          redirectUrl: Linking.createURL('dashboard', { scheme: 'myapp' }),
-        })
-
-        // The rest of your code...
-      }, [])
-      ```
+1. Scroll to the **Allowlist for mobile SSO redirect** section and add your redirect URLs.
+   1. The default is `<INSERT-YOUR-APP-SCHEME>://sso-callback`
 
 > [!TIP]
 > You can also add redirect URLs via [the Backend API](/docs/reference/backend-api/tag/Redirect-URLs#operation/CreateRedirectURL){{ target: '_blank' }}.

docs/manifest.json

@@ -2174,8 +2174,8 @@
                           "href": "/docs/references/javascript/types/metadata"
                         },
                         {
-                          "title": "OAuth types",
-                          "href": "/docs/references/javascript/types/oauth"
+                          "title": "SSO types",
+                          "href": "/docs/references/javascript/types/sso"
                         },
                         {
                           "title": "`OrganizationDomain`",
@@ -2443,7 +2443,11 @@
                           "href": "/docs/references/expo/use-local-credentials"
                         },
                         {
-                          "title": "useOAuth()",
+                          "title": "`useSSO()`",
+                          "href": "/docs/references/expo/use-sso"
+                        },
+                        {
+                          "title": "`useOAuth()` (deprecated)",
                           "href": "/docs/references/expo/use-oauth"
                         }
                       ]

docs/references/backend/user/get-user-oauth-access-token.mdx

@@ -25,7 +25,7 @@ function getUserOauthAccessToken(
   ---
 
   - `provider`
-  - <code>oauth\_$\{[OAuthProvider](/docs/references/javascript/types/oauth#o-auth-provider)}</code>
+  - <code>oauth\_$\{[OAuthProvider](/docs/references/javascript/types/sso#o-auth-provider)}</code>
 
   The OAuth provider to retrieve the access token for. If using a custom OAuth provider, prefix the provider name with `oauth_custom_` (e.g., `oauth_custom_foo`).
 </Properties>

docs/references/expo/overview.mdx

@@ -14,7 +14,7 @@ The Expo SDK gives you access to the following resources:
 The following hooks are available for both **native** and **web** apps:
 
 - All React hooks are available. See [the React docs](/docs/references/react/overview){{ target: '_blank' }} for more information.
-- [`useOAuth()`](/docs/references/expo/use-oauth)
+- [`useSSO()`](/docs/references/expo/use-sso)
 - [`useLocalCredentials()`](/docs/references/expo/use-local-credentials)
 
 ### Clerk components {{ id: 'components' }}

docs/references/expo/use-oauth.mdx

@@ -1,15 +1,18 @@
 ---
-title: '`useOAuth()`'
+title: useOAuth()
 description: Clerk's useOAuth() hook is used to create a new OAuth flow.
 ---
 
+> [!WARNING]
+> This feature is deprecated. Use [`useSSO()`](/docs/references/expo/use-sso) instead.
+
 The `useOAuth()` hook is used to create a new OAuth flow. It can be used in both web and native apps.
 
 ## Parameters
 
 <Properties>
   - `strategy`
-  - [`OAuthStrategy`](/docs/references/javascript/types/oauth#o-auth-strategy)
+  - [`OAuthStrategy`](/docs/references/javascript/types/sso#o-auth-strategy)
 
   The strategy corresponding to the OAuth provider. For example: `oauth_facebook`, `oauth_github`, etc.
 
@@ -46,7 +49,7 @@ It accepts the following parameters (`StartOAuthFlowParams`):
   - `redirectUrl?`
   - `string`
 
-  The full URL or path to redirect to after the OAuth flow is complete.
+  The URL or path to redirect to after the OAuth flow is complete.
 
   ---
 
@@ -58,4 +61,4 @@ It accepts the following parameters (`StartOAuthFlowParams`):
 
 ## How to use the `useOAuth()` hook
 
-<Include src="_partials/expo/oauth-custom-flow" />
+<Include src="_partials/expo/deprecated-oauth-custom-flow" />

docs/references/expo/use-sso.mdx

@@ -0,0 +1,58 @@
+---
+title: useSSO()
+description: Clerk's useSSO() hook is used to create a new SSO flow.
+---
+
+The `useSSO()` hook is used to create a new SSO flow. It can be used in both web and native apps.
+
+## Returns
+
+The `useSSO()` hook returns the `startSSOFlow()` method, which you can use to initiate the SSO flow.
+
+It accepts the following parameters (`StartSSOFlowParams`):
+
+## Parameters
+
+<Properties>
+  - `strategy`
+  - `'oauth_<provider>'` | `'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/overview). [See a list of supported values for `<provider>`](/docs/references/javascript/types/sso#o-auth-provider).
+  - `'enterprise_sso'`: The user will be authenticated either through SAML, EASIE, or OIDC depending on the configuration of their [enterprise SSO account](/docs/authentication/enterprise-connections/overview).
+
+  ---
+
+  - `identifier?`
+  - string
+
+  **Required** if `strategy` is set to `'enterprise_sso'`. The [identifier](/docs/authentication/configuration/sign-up-sign-in-options#identifier) of the user.
+
+  ---
+
+  - `unsafeMetadata?`
+  - [`SignUpUnsafeMetadata`](/docs/references/javascript/types/metadata#sign-up-unsafe-metadata)
+
+  Metadata that can be read and set from the frontend and the backend. Once the authentication process is complete, the value of this field will be automatically copied to the created user's unsafe metadata (`User.unsafeMetadata`). One common use case is to collect custom information about the user during the authentication process and store it in this property. Read more about [unsafe metadata](/docs/users/metadata#unsafe-metadata).
+</Properties>
+
+## How to use the `useSSO()` hook
+
+Clerk ensures that security critical nonces will be passed only to allowlisted URLs when the SSO flow is complete in native browsers or webviews.
+
+So for maximum security in your production instances, you need to allowlist your the SSO callback URL in your Clerk Dashboard by following these steps:
+
+1. Navigate to [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections)
+1. Under **Allowlist for mobile SSO redirect**, add `<INSERT-YOUR-APP-SCHEME>://sso-callback`
+
+> [!TIP]
+> You can also add redirect URLs via [the Backend API](/docs/reference/backend-api/tag/Redirect-URLs#operation/CreateRedirectURL){{ target: '_blank' }}.
+
+### With OAuth
+
+<Include src="_partials/expo/oauth-custom-flow" />
+
+### With SAML
+
+<Include src="_partials/expo/enterprise-sso-custom-flow" />

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

@@ -19,11 +19,11 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi
 
 <Properties>
   - `strategy`
-  - <code>[OAuthStrategy](/docs/references/javascript/types/oauth#o-auth-strategy) | 'saml' | 'enterprise\_sso'</code>
+  - <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/overview). See a list of [supported values for `<provider>`](/docs/references/javascript/types/oauth).
+  - `'oauth_<provider>'`: The user will be authenticated with their [social connection account](/docs/authentication/social-connections/overview). 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).
 

docs/references/javascript/sign-in/first-factor.mdx

@@ -21,7 +21,7 @@ function prepareFirstFactor(params: PrepareFirstFactorParams): Promise<SignIn>
 
 <Properties>
   - `strategy`
-  - `'email_link' | 'email_code' | 'phone_code' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'passkey' | 'oauth_<provider>' | 'enterprise_sso' | 'reset_password_phone_code' | 'reset_password_email_code'`
+  - `'email_link' | 'email_code' | 'phone_code' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'passkey' | 'oauth_<provider>' | 'saml' | 'enterprise_sso' | 'reset_password_phone_code' | 'reset_password_email_code'`
 
   The `strategy` value depends on the `SignIn.identifier` value. Each authentication identifier supports different verification strategies. The following strategies are supported:
 
@@ -32,7 +32,7 @@ function prepareFirstFactor(params: PrepareFirstFactorParams): Promise<SignIn>
   - `'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). Requires `web3WalletId` parameter to be set.
   - `'web3_okx_wallet_signature'`: The verification will attempt to be completed using the user's Web3 wallet address via [OKX Wallet](https://www.okx.com/help/section/faq-web3-wallet). Requires `web3WalletId` parameter to be set.
   - `'passkey'`: The verification will attempt to be completed using the user's passkey.
-  - `'oauth_<provider>'`: The user will be authenticated with their [social connection account](/docs/authentication/social-connections/overview). See a list of [supported values for `<provider>`](/docs/references/javascript/types/oauth).
+  - `'oauth_<provider>'`: The user will be authenticated with their [social connection account](/docs/authentication/social-connections/overview). 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).
   - `'reset_password_phone_code'`: Used when the user is trying to reset their password. The user will receive a one-time code via SMS. Requires `phoneNumberId` parameter to be set.

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

@@ -119,7 +119,7 @@ function create(params: SignInCreateParams): Promise<SignIn>
   - `'email_link'`: User will receive an email magic link via email. The `identifier` parameter can also be specified to select one of the user's known email addresses. The `redirectUrl` parameter can also be specified.
   - `'email_code'`: User will receive a one-time authentication code via email. The `identifier` parameter can also be specified to select one of the user's known email addresses.
   - `'phone_code'`: User will receive a one-time authentication code via SMS. The `identifier` parameter can also be specified to select one of the user's known phone numbers.
-  - `'oauth_<provider>'`: The user will be authenticated with their [social connection account](/docs/authentication/social-connections/overview). See a list of [supported values for `<provider>`](/docs/references/javascript/types/oauth).
+  - `'oauth_<provider>'`: The user will be authenticated with their [social connection account](/docs/authentication/social-connections/overview). 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).
   - `'passkey'`: The user will be authenticated with their [passkey](/docs/authentication/configuration/sign-up-sign-in-options#passkeys).