Connect Google OAuth

Learn how to configure Google Workspace via OAuth

Introduction

To configure your global Google OAuth setup, you'll need three pieces of information: a Redirect URI, a Google Client ID, and a Google Client Secret.

WorkOS Provides

WorkOS provides the Redirect URI, an allowlisted callback URL. It indicates the location to return an authorized user to after both an authorization code is granted, and the authentication process is complete.

Simply open your WorkOS Dashboard, browse to the 'Configuration' tab on the left hand nav bar. Scroll down to the 'Google Settings' and you'll see the Redirect URI as well as the fields you'll populate later with information from Google.

Overview

And then, you provide the Google Client ID and the Google Client Secret.

These are a pair of credentials provided by Google that you'll use to authenticate your application via Google's OAuth protocol. To obtain them:

1

Log in

Log in to the Google Cloud Platform Console Dashboard. Select your application's project from the project selection dropdown menu in the navigation bar.

2

Select your application

Select "APIs & Services", then "OAuth Consent Screen" in the left-hand navigation menu.

Select "Edit App".

Add workos.com to your list of "Authorized domains", and select "Save".

3

Enter Setup Instructions

Select "Credentials" in the left-hand menu. Then select "OAuth client ID" from the "Create Credentials" dropdown menu.

Then, give your OAuth client ID a name, and add the Redirect URI provided by WorkOS to the list of "Authorized redirect URIs".

As a best practice, your OAuth client ID's name should be different from your application's name. It will not be shown to end users.

Click "Create" and you'll be presented with your application's Client ID and Client Secret!

4

Obtain Identity Provider Details

Add your Google Client ID and Google Client Secret to their respective fields in your Google Settings in the Configuration section of the WorkOS Dashboard.

Select "Save Google OAuth" and you'll be ready to go!

After that, you're now able to authenticate users with Google OAuth. Provide the provider parameter when authenticating Google OAuth users, because Google OAuth does not take a user’s domain into account when logging in with a “Sign in with Google” button. You will use theprovider query parameter in the Get Authorization URL API endpoint to support global Google OAuth for any domain. The provider query parameter should be set to GoogleOAuth.

Customize Google OAuth Domain

Optional process that requires access to your Google Cloud Console and your domain's DNS settings.

Overview

After implementing the steps above, you'll notice that the Google OAuth sign in form displays "Choose an account to continue to workos.com". This is based on the Authorized Redirect URI in Google. To set this to a domain other than workos.com, Google will ask for proof of ownership of your domain. To help guide you through this process we have a self-service flow.

1

Add Your Custom Google OAuth Domain

In the Configuration tab of the WorkOS Dashboard, find the Google OAuth section and click on "Setup Custom Domain". Note: This button will only appear if your environment has a valid Google OAuth configuration and has not already setup a custom domain.

Under "Add Custom Domain", input the domain that you wish to use in place of auth.workos.com. This is often a subdomain such as auth.example.com. Click on "Set Domain".

2

Add CNAME Target

Add a new CNAME target inside your domain's DNS settings. Set the host to match the domain you set in the previous step and set the value to cname.workosdns.com.

Once the above is complete, click on "Verify DNS". This verification often takes less than a minute, but is dependent on how long your DNS record takes to propagate. The page will continue polling to check the status of your verification until it is successful.

3

Add New Redirect URI to Google

Once the DNS has been successfully verified, you will see a URI starting with your subdomain in the "Add redirect URI to Google" section. Click on the clipboard icon to copy the URL.

In your Google Cloud Platform dashboard under your project's "APIs & Services" > "Credentials" section, add the URL copied above under "Authorized redirect URIs". To ensure your Google OAuth integration continues to work without any gaps in service, leave your existing Redirect URI in place for now.

4

Test Google Redirect URI

Once the URL has been added and saved on the Google side, navigate back to the WorkOS Dashboard and click on "Test Google Redirect URI".

If the test is successful, you will see a "Successfully tested" message displayed.

Save your new Google OAuth configuration by clicking "Save custom Google OAuth settings".

Once these updates have been saved, test out your Google OAuth sign in flow to ensure everything is working properly and your domain is displayed on the form. If everything is looking good, it is safe to remove the old auth.workos.com URL from your Google Authorized redirect URIs.

Frequently asked questions

How is the WorkOS Google OAuth integration different from implementing regular Google OAuth flow?

It’s the same Google OAuth flow as you could build yourself, but it’s encapsulated within WorkOS SSO. This just means you don’t need to build it yourself. In addition to Google OAuth, you can use WorkOS SSO to support other identity providers, all with a single integration.

What is the provider query parameter and how is it used in the Google OAuth integration?

You can use the provider query parameter in the Get Authorization URL API endpoint to support global Google OAuth for any domain. The provider query parameter should be set to GoogleOAuth.