Google OAuth

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.

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

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

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

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

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.

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.

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. You will also now be able to 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 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.