WorkOS Docs Homepage

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.

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.

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

Select “Edit App”.

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

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!

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 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”. This is based on the Authorized Redirect URI in Google. To set this to a domain other than, 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.

Under “Add Custom Domain”, input the domain that you wish to use in place of This is often a subdomain such as Click on “Set Domain”.

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

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.

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.

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.

Click “Save custom Google OAuth settings” to save your new Google OAuth configuration.

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 URL from your Google Authorized redirect URIs, and 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 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.