How to set up social connection with Google
Overview
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.
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 production instances, you will need to create your own developer account with Google and generate your own Client ID and Client secret.
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.
Before you start
- You need to create a Clerk Application in your Clerk Dashboard(opens in a new tab). For more information, check out our Set up your application guide.
- You need to have a Google Developer account. To create one, visit the Google Cloud console(opens in a new tab).
Configuring Google social connection
First, in the Clerk Dashboard, go to User & Authentication > Social Connections(opens in a new tab). From the list of OAuth vendors, toggle on the Google option. In the modal that opened, make sure Use custom credentials is enabled, 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.
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(opens in a new tab). In the Authorized redirect URIs setting, paste the value you copied from Clerk's Dashboard (see previous paragraph).
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.
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.
Optionally, you can also set additional OAuth scopes that your application might need, according to your use case. More information about this feature can be found here(opens in a new tab), while the list of Google's available scopes can be found here(opens in a new tab).
As a quick recap, if you followed this guide, you should have done the following:
- 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
In the Clerk Dashboard configuration screen, you should end up with something like this:
Finally, click Save so that the settings are applied. Congratulations! Social connection with Google is now configured for your instance.
Important note about switching to production
Google OAuth apps by default start off in the "Testing" publishing status(opens in a new tab). 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(opens in a new tab). 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.
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.
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.
Block email subaddresses
In the Clerk Dashboard configuration screen, you also have an 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 domain example.com, blocking email subaddresses will prevent someone with access to email user@example.com from signing up with email user+alias@example.com. This is a known Google OAuth vulnerability(opens in a new tab) 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.
Existing Google accounts with email subaddresses will be blocked by this restriction and will not be able to sign in.