(/social-connections/google) update guide (#1590)

Co-authored-by: victoria <[email protected]>

docs/authentication/social-connections/google.mdx

@@ -1,87 +1,107 @@
 ---
 title: Add Google as a social connection
-description: Learn how to set up social connection with Google.
+description: Learn how to allow users to sign up and sign in to your Clerk app with their Google account using OAuth.
 ---
 
-How to set up social connection with Google
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "A Clerk application is required.",
+      link: "/docs/quickstarts/setup-clerk",
+      icon: "clerk",
+    },
+    {
+      title: "A Google Developer account is required.",
+      link: "https://console.developers.google.com/",
+      icon: "user-circle",
+    }
+  ]}
+>
+  - Use Google to authenticate users with OAuth.
+</TutorialHero>
 
-## Overview
+Enabling OAuth with Google allows your users to sign up and sign in to your Clerk application with their Google account.
 
-Adding social connection with Google to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings.
+## Configure for your development instance
 
-To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed.
+For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed.
 
-For production instances, you will need to create your own developer account with Google and generate your own Client ID and Client secret.
+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 all users**.
+1. In the **Choose provider** dropdown, select **Google**.
+1. Select **Add connection**.
 
-> [!NOTE]
-> The purpose of this guide is to help you setup a Google developer account and a Google OAuth 2.0 project - if you're looking for step-by-step  instructions using Clerk to add Social Connection (OAuth) to your  application, follow the [Social connection (OAuth) guide](/docs/authentication/social-connections/oauth).
-
-## Before you start
+## Configure for your production instance
 
-- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk).
-- You need to have a Google Developer account. To create one, visit the [Google Cloud console](https://console.developers.google.com/).
+In _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Google Developer account.
 
-## Configuring Google social connection
+To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/).
 
-Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Google**. Toggle on **Use custom credentials** and copy the value of the **Authorized redirect URI** field (you will have to paste this in the Google Console in a bit). Leave that window open as you will need to fill in the Client ID and Client Secret values that you will retrieve from the Google Cloud Platform console.
+<Steps>
+  ### Enable Google as a social connection
 
-In a new window, go to your Google Cloud Platform console. Select your Google project (step 1 in the screenshot) and enable OAuth 2.0 support by following the official instructions on [how to set up up an OAuth 2.0 application](https://support.google.com/cloud/answer/6158849?hl=en). In the **Authorized redirect URIs** setting, paste the value you copied from Clerk's Dashboard (see previous paragraph).
+  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 all users**.
+  1. In the **Choose provider** dropdown, select **Google**.
+  1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on.
+  1. Save the **Authorized redirect URI** somewhere secure. Keep this modal and page open.
 
-![Creating an OAuth client ID in Google Cloud console](/docs/images/authentication-providers/google/700f6f127f579f46032602391223bb42bd807b06-1696x992.png)
+  ### Create a Google Developer project
 
-Once you have an OAuth client ID created, click on the newly created ID under **OAuth 2.0 Client IDs**. Copy the values of **Your Client ID** and **Your Client secret**; they will be needed in a minute.
+  1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/).
+  1. Select a project or [create a new one](https://console.cloud.google.com/projectcreate).
+  1. If the **APIs & Services** page isn't already open, open the menu on the left and select **APIs & Services**.
+  1. In the menu on the left, select **Credentials**.
+  1. Select **Create Credentials**. Then, select **OAuth client ID.** You may need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849?hl=en#userconsent\&zippy=%2Cuser-consent).
+  1. Select the appropriate application type for your project. Most likely, you will choose **Web application**.
+  1. In the **Authorized redirect URIs** setting, add the **Authorized redirect URI** value you saved from the Clerk Dashboard.
+  1. Select **Create**. Keep this page open.
 
-![Copy the Client ID and Client Secret](/docs/images/authentication-providers/google/097b6afe678dc7c07efe5e6fc5ca78b46a002ee5-1696x992.png)
+  ### Set the Client ID and Client Secret in your Clerk Dashboard
 
-Go back to your Clerk instance's Dashboard and in the modal that should be opened (see beginning of this section), paste the **Client ID** and **Client Secret** values you obtained during the previous step.
+  Once the OAuth client is created in the Google Cloud Console, a modal will open with your **Client ID** and **Client Secret**. Save these values somewhere secure.
 
-Optionally, you can also [set additional OAuth scopes that your application might need, according to your use case.](/docs/authentication/social-connections/oauth) The list of Google's available scopes can be found [here](https://developers.google.com/identity/protocols/oauth2/scopes).
+  Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. Then, select **Add connection**.
 
-As a quick recap, if you followed this guide, you should have done the following:
+  > [!NOTE]
+  > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **Google** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields.
 
-- Created an OAuth client ID in Google Cloud Platform console
-- Added the authorized redirect URI in that OAuth client ID, as provided by Clerk Dashboard
-- Set the proper Client ID and Client secret values in Clerk Dashboard, as provided by the Google Cloud Platform console
+  ### Test your OAuth
 
-In the Clerk Dashboard, you should end up with something like this:
+  The simplest way to test your OAuth 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.
 
-![Client ID and Client secret filled in. Authorized redirect URI copied and entered into Google Cloud Platform console.](/docs/images/authentication-providers/google/configuration.png)
-
-Finally, select **Add connection** so that the settings are applied. Congratulations! Social connection with Google is now configured for your instance.
+  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 Google account.
+</Steps>
 
 ### Important note about switching to production
 
-Google OAuth apps by default start off in the "Testing" [publishing status](https://support.google.com/cloud/answer/10311615#publishing-status).
-The publishing status setting can be found at the **APIs & Services > OAuth consent screen** page within the Google Cloud Platform console.
-
-"Testing" mode is intended for internal testing prior to opening Google Auth connections to your [intended audience](https://support.google.com/cloud/answer/10311615#user-type).
-It is limited to 100 test users and depending on the requested OAuth scopes, they may need to be explicitly added to your trusted user list to be able to connect.
+Google OAuth apps have a publishing status that determines who can access the app. The publishing status setting can be found within the Google Cloud Platform console on the **APIs & Services > OAuth consent screen** page. You can only view the publishing status if the **User type** is set to **External**.
 
-Once ready to switch your Google OAuth app to production, you will need to set the publishing status to "In Production".
-This involves a verification process with regard to your application name, logo and scopes requested before Google accepts the switch to production.
+By default, Google OAuth apps are set to the "Testing" [publishing status](https://support.google.com/cloud/answer/10311615#publishing-status), which is intended for internal testing before opening connections to your [intended audience](https://support.google.com/cloud/answer/10311615#user-type). It is limited to 100 test users and depending on the requested OAuth scopes, they may need to be explicitly added to your trusted user list to be able to connect.
 
-Please make sure your production application always uses a corresponding Google OAuth app that is set to "In Production" publishing status, so that your end users do not encounter any issues connecting.
+To switch a Google OAuth app to production, **you must set the publishing status to "In production".** This involves a verification process with regard to your app name, logo and scopes requested before Google accepts the switch to production.
 
-![Publishing status setting within Google Cloud Platform console.](/docs/images/authentication-providers/google/oauth_google_consent_screen.png)
+Make sure that your Clerk production app always uses a corresponding Google OAuth app that is set to the "In Production" publishing status, so that your end users do not encounter any issues using Google as a social connection.
 
 ### Block email subaddresses
 
-![Block email subaddresses enabled for Google social connection.](/docs/images/authentication-providers/google/google-block-email-subaddresses.png)
+By default, your app will block any Google account with an email address that contains the characters `+`, `=` or `#` from being able to sign up, sign in, or be added to existing accounts.
 
-In the Google social connection configuration modal, you also have the option to block email subaddresses. With this setting on, any Google account with an email address that contains the characters `+`, `=` or `#` will not be able to sign in, sign up, or be added to existing accounts. By default, this setting will be enabled for new Google social connections.
+For a Google organization with the domain `example.com`, blocking email subaddresses prevents someone with access to `[email protected]` from signing up with `[email protected]`. This is a known [Google OAuth vulnerability](https://trufflesecurity.com/blog/google-oauth-is-broken-sort-of/) that could allow unauthorized, as Google organization administrators cannot suspend or delete the email alias account. It's recommended to keep this setting enabled for enhanced security.
 
-For a Google organization with domain `example.com`, blocking email subaddresses will prevent someone with access to email `[email protected]` from signing up with email `[email protected]`. This is a known [Google OAuth vulnerability](https://trufflesecurity.com/blog/google-oauth-is-broken-sort-of/) that could allow unauthorized access since there is no way for a Google organization administrator to suspend or delete the email alias account. As a result, we recommend enabling this setting for Google OAuth.
+To configure this setting:
+
+1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
+1. Select the **Google** connection.
+1. Enable or disable **Block email subaddresses**.
 
 > [!NOTE]
 > Existing Google accounts with email subaddresses will be blocked by this restriction and will not be able to sign in.
 
 ## Google One Tap
 
-[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) enables users to sign-in or sign-up to your Clerk application with the press of a button. After adding Google to your Clerk app as a social connection, you can use Clerk's prebuilt `<GoogleOneTap />` component to render the One Tap UI in your app.
-
-See [the `<GoogleOneTap />` component reference](/docs/components/authentication/google-one-tap) to learn more.
-
-## References
-
-- [OAuth API verification FAQs](https://support.google.com/cloud/answer/9110914#)
-- [Setting up your OAuth consent screen](https://support.google.com/cloud/answer/10311615)
+[Google One Tap](https://developers.google.com/identity/gsi/web/guides/features) enables users to sign up or sign in to your Clerk app with the press of a button. After adding Google to your Clerk app as a social connection, you can use Clerk's prebuilt `<GoogleOneTap />` component to render the One Tap UI in your app. See [the `<GoogleOneTap />` component reference](/docs/components/authentication/google-one-tap) to learn more.