Merge branch 'main' into rob/eco-224-nuxt-quickstart

CONTRIBUTING.md

@@ -439,18 +439,18 @@ console.log('ignored')
 
 ### `<Steps />`
 
-The `<Steps />` component is used to number a set of instructions with an outcome. It uses the highest heading available in the component to denote each step. Can be used with `h3` headings.
+The `<Steps />` component is used to number a set of instructions with an outcome. It uses the highest heading available in the component to denote each step. Can be used with `h2` and `h3` headings.
 
 ```mdx
 <Steps>
 
-### Step 1
+## Step 1
 
 Do these actions to complete Step 1.
 
-### Another step
+## Another step
 
-#### A heading inside a step
+### A heading inside a step
 
 Do these actions to complete Step 2.
 
@@ -575,7 +575,7 @@ The `<TutorialHero />` component is used at the beginning of a tutorial-type con
 
 - Install `@clerk/nextjs`
 - Set up your environment keys to test your app locally
-- Add `<ClerkProvider />` to your application
+- Add `<ClerkProvider>` to your application
 - Use Clerk middleware to implement route-specific authentication
 - Create a header with Clerk components for users to sign in and out
 

docs/_partials/clerk-provider.mdx

@@ -0,0 +1 @@
+The [`<ClerkProvider>`](/docs/components/clerk-provider) component provides session and user context to Clerk's hooks and components. It's recommended to wrap your entire app at the entry point with `<ClerkProvider>` to make authentication globally accessible. See the [reference docs](/docs/components/clerk-provider) for other configuration options.

docs/_partials/expo/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/react-hooks.mdx

@@ -0,0 +1,9 @@
+- [`useUser()`](/docs/references/react/use-user){{ target: '_blank' }}
+- [`useClerk()`](/docs/references/react/use-clerk){{ target: '_blank' }}
+- [`useAuth()`](/docs/references/react/use-auth){{ target: '_blank' }}
+- [`useSignIn()`](/docs/references/react/use-sign-in){{ target: '_blank' }}
+- [`useSignUp()`](/docs/references/react/use-sign-up){{ target: '_blank' }}
+- [`useSession()`](/docs/references/react/use-session){{ target: '_blank' }}
+- [`useSessionList()`](/docs/references/react/use-session-list){{ target: '_blank' }}
+- [`useOrganization()`](/docs/references/react/use-organization){{ target: '_blank' }}
+- [`useOrganizationList()`](/docs/references/react/use-organization-list){{ target: '_blank' }}

docs/advanced-usage/satellite-domains.mdx

@@ -115,7 +115,7 @@ To access authentication state from a satellite domain, users will be transparen
           # CLERK_SIGN_UP_URL=http://localhost:3000/sign-up
           ```
         </CodeBlockTabs>
-      - You will also need to add the `allowedRedirectOrigins` property to `<ClerkProvider />` on your _primary domain app_ to ensure that the redirect back from primary to satellite domain works correctly. For example:
+      - You will also need to add the `allowedRedirectOrigins` property to `<ClerkProvider>` on your _primary domain app_ to ensure that the redirect back from primary to satellite domain works correctly. For example:
 
         <CodeBlockTabs options={["Development", "Production"]}>
           ```tsx {{ filename: 'app/layout.tsx' }}

docs/authentication/configuration/sign-up-sign-in-options.mdx

@@ -17,7 +17,7 @@ Identifiers are how your application recognizes an individual user. There are th
 
 In the application configuration screen, you can select multiple identifiers, but at least one is required.
 
-**Email address** is the most common primary identifier. During the sign-up process, a user must supply and verify their email address. They must keep an email address on their account at all times. However, the email address that was used for registration can be later changed from the user's profile page.
+**Email address** is the most common primary identifier. When it is the only enabled identifier, users are required to supply an email address during sign-up and keep one on their account at all times. The email address that was supplied during sign-up can be later changed from the user's profile page.
 
 When **phone number** is selected as the identifier, a user can sign up with their phone number and receive a code via SMS to verify it. SMS functionality is restricted to phone numbers from countries enabled on your [SMS allowlist](#sms-allowlist).
 
@@ -162,12 +162,12 @@ To enable social connections:
 
 ## Web3 authentication
 
-Clerk provides [Web3 authentication](/docs/users/web3) with either MetaMask or Coinbase Wallet. As part of validating the accuracy of the returned Web3 account address, Clerk handles the signing of a message and verifying the signature. Because sign-in with Web3 uses the same abstraction as our other authentication factors, like passwords or email links, other Clerk features like multi-factor authentication and profile enrichment work for Web3 users out-of-the-box.
+Clerk provides [Web3 authentication](/docs/users/web3) with either MetaMask, Coinbase Wallet or OKX Wallet. As part of validating the accuracy of the returned Web3 account address, Clerk handles the signing of a message and verifying the signature. Because sign-in with Web3 uses the same abstraction as our other authentication factors, like passwords or email links, other Clerk features like multi-factor authentication and profile enrichment work for Web3 users out-of-the-box.
 
 To enable Web3 authentication:
 
 1. In the Clerk Dashboard, navigate to the [**Web3**](https://dashboard.clerk.com/last-active?path=user-authentication/web3) page.
-1. Toggle on the Web3 provider. Currently, Clerk supports MetaMask and Coinbase Wallet.
+1. Enable your preferred Web3 provider.
 
 ## Multi-factor authentication
 

docs/authentication/enterprise-connections/easie/microsoft.mdx

@@ -74,7 +74,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
 
   [nOAuth](https://www.descope.com/blog/post/noauth) is an exploit in Microsoft Entra ID OAuth apps that can lead to account takeovers via email address spoofing. Clerk mitigates this risk by enforcing stricter checks on verified email addresses.
 
-  For further security, Microsoft offers an optional `xms_edov` claim, which provides additional context to determine whether the returned email is verified.
+  For further security, Microsoft offers an optional `xms_edov` [claim](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims-reference), which provides additional context to determine whether the returned email is verified.
 
   This claim is mandatory for applications backing EASIE connections. To enable it, you must:
 
@@ -83,8 +83,6 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   1. Select **Add optional claim**.
   1. For the **Token type**, select **ID**. Then, in the table that opens, enable the `email` and `xms_pdl` claims.
   1. At the bottom of the modal, select **Add**. A new modal will prompt you to turn on the Microsoft Graph email permission. Enable it, then select **Add** to complete the form.
-     > [!NOTE]
-     > At the time of writing, the `xms_edov` claim is still in preview and may not be available for all apps. We'll choose another claim and rename it in the manifest later.
   1. Repeat the previous steps for **Token type**, but select **Access** instead of **ID**. The **Optional claims** list should now show two claims for `email` and two for `xms_pdl`: one each for **ID** and **Access**.
   1. In the sidebar, go to **Manifest**.
   1. In the text editor, search for `"acceptMappedClaims"` and set its value from `null` to `true`.

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

@@ -0,0 +1,88 @@
+---
+title: Add a custom OpenID Connect (OIDC) Provider as an enterprise connection
+description: Learn how to integrate a custom OIDC provider with Clerk for Enterprise SSO.
+---
+
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "Add the Enhanced Authentication add-on to your Pro plan",
+      link: "/pricing",
+      icon: "plus-circle",
+    },
+    {
+      title: "Enable email address as an identifier for your app",
+      link: "/docs/authentication/configuration/sign-up-sign-in-options#identifiers",
+      icon: "key",
+    },
+  ]}
+>
+  - Add a custom OIDC provider to authenticate users with Enterprise SSO
+</TutorialHero>
+
+This guide explains how to use a custom [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works) provider to authenticate users via Enterprise SSO.
+
+To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your Identity Provider (IdP).
+
+<Steps>
+  ## Set up an enterprise connection in Clerk
+
+  1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
+  1. Select **Add connection** and select **For specific domains**.
+  1. Under **Third party**, select **OpenID Connect (OIDC)**.
+  1. Add the **Name** of the connection.
+  1. Add the **Key** of the provider. This is the provider's unique identifier (cannot be changed after creation).
+  1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app.
+  1. Select **Add connection**. You will be redirected to the connection's configuration page. Keep this page open.
+
+  ## Configure your IdP
+
+  1. If necessary, create a new application in your IdP.
+  1. In the connection's configuration page of the Clerk Dashboard, copy the **Authorized redirect URI**.
+  1. Add the value to your IdP's whitelisted URLs.
+  1. Find your application's **Discovery Endpoint**, **Client ID**, and **Client Secret** and copy them.
+
+  ## Set the Discovery Endpoint, Client ID, and Client Secret in Clerk
+
+  1. In your IdP settings, copy your application's **Discovery Endpoint**, **Client ID**, and **Client Secret**.
+  1. In the connection's configuration page in the Clerk Dashboard, paste these values in their respective fields.
+  1. Under **Scopes**, add the minimum required scopes based on the IdP's documentation if needed. Common OIDC scopes include `openid`, `email`, and `profile`.
+  1. Select **Save**.
+
+  > [!NOTE]
+  > Most IdPs provide a **Discovery Endpoint** to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, in the connection's configuration page in the Clerk Dashboard, find the **Identity Provider Configuration** section and select **Use Manual Configuration** to manually configure the connection.
+
+  ## Configure attribute mapping (optional)
+
+  Clerk expects the claims returned by your IdP to follow the [OIDC Standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes.
+
+  > [!WARNING]
+  > OIDC Enterprise connections require the [`email_verified`](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims:~:text=Section%C2%A05.7.-,email_verified,-boolean) claim to verify email ownership. However, some IdPs, such as Microsoft Azure Active Directory, might not return this claim or use a non-standard format.
+  >
+  > If the IdP doesn't return this claim, you can leave the **Email address verified** field blank and set the **Default value** to **True**. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth).
+
+  ## Allow additional identifiers (optional)
+
+  User profile information is sourced from the IdP. To allow users to add new identifiers (e.g., email address or phone number) to their profiles:
+
+  1. In the connection's configuration page of the Clerk Dashboard, navigate to the **Advanced** tab.
+  1. Enable **Allow additional identifiers**.
+  1. Select **Save**.
+
+  ## Enable the connection for Clerk
+
+  To make the connection available for your users to authenticate with:
+
+  1. Navigate back to the Clerk Dashboard where you should still have the connection's configuration page open. If not, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection.
+  1. At the top of the page, toggle on **Enable connection** and select **Save**.
+
+  ## Test your connection
+
+  The simplest way to test your enterprise connection is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box.
+
+  1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page.
+  1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble:
+     - **For development** – `https://your-domain.accounts.dev/sign-in`
+     - **For production** – `https://accounts.your-domain.com/sign-in`
+  1. Sign in with your IdP account.
+</Steps>