WorkOS Docs Homepage
Integrations

Google OAuth

Learn how to set up OAuth with Google Workspace.

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 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.

Open your WorkOS Dashboard and browse to the “Configuration” tab on the left hand nav bar. Scroll down to the “Google OAuth” section and you’ll see the Redirect URI as well as the fields you’ll populate later with information from Google.

A screenshot showing the Google OAuth Redirect URI in the WorkOS Dashboard.

WorkOS provides a default Google Client ID/Google Client Secret combination, which allows you to quickly enable and test Google OAuth. Use the WorkOS API to initiate SSO, setting the provider parameter to GoogleOAuth, and WorkOS will automatically use the default credentials, until you add your own Google Client ID and Google Client Secret to the Configuration in the WorkOS Dashboard.

The default credentials are only intended for testing and therefore only available in the Staging environment. For your production environment, please follow the steps below to create and specify your own Google Client ID and Google Client Secret.

Please note that when you are using WorkOS default credentials, Google’s authentication flow will display WorkOS’ name, logo, and other information to users. Once you register your own application and use its Google Client ID and Google Client Secret for the OAuth flow, you will have the opportunity to customize the app, including its name, logo, contact email, etc.

In order to integrate you’ll need 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:

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

A screenshot showing how to select your application in the Google Cloud Platform Console Dashboard.

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

A screenshot showing where to find the "OAuth Consent Screen" option in the Google Cloud Platform Console Dashboard.

Select “Edit App”.

A screenshot showing where "Edit App" is located in the Google Cloud Platform Console Dashboard.

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

A screenshot showing where to enter workos.com as an "Authorized domain" in the Google Cloud Platform Console Dashboard.

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

A screenshot showing where to find the "OAuth client ID" option in the Google Cloud Platform Console Dashboard.

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.

A screenshot showing where to enter your WorkOS Redirect URI in the Google Cloud Platform Console Dashboard.

Click “Create” and you’ll be presented with your application’s Client ID and Client Secret.

A screenshot showing the Client ID and Client Secret in the Google Cloud Platform Console Dashboard.

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.

A screenshot showing where to enter the Google Client ID and Google Client Secret in the WorkOS Dashboard.

Select “Save Google OAuth” and you’ll almost be ready to go.

Back in the “OAuth consent screen”, be sure that your app is “In production”. If it is still in testing mode you’ll likely get an “Access Blocked” error when attempting to log into your app.

A screenshot showing the publishing status of your Google OAuth application

After that, you’re now able to authenticate users with Google OAuth. You will 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.

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

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.

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.

A screenshot showing where to find the "Set Up Custom Domain" button in the WorkOS Dashboard.

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”.

A screenshot showing where to add a custom domain in the WorkOS Dashboard.

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.

A screenshot showing the CNAME target of cname.workosdns.com in the WorkOS Dashboard.

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

A screenshot showing the clipboard icon in the WorkOS Dashboard.

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.

A screenshot showing where to enter the redirect URI in the Google Cloud Platform Console.

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”.

A screenshot showing the "Test Google Redirect URI" button in the WorkOS Dashboard.

If the test is successful, you will see a “Successfully tested” message displayed. You will also now be able to click “Save custom Google OAuth settings” to save your new Google OAuth configuration.

A screenshot showing the "Save custom Google OAuth settings" button in the WorkOS Dashboard.

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, and workos.com from your Google Authorized domains.

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 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.