Connect G Suite OAuth

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. It's readily available in your Connection's Settings in Developer Dashboard.

Configuring G Suite OAuth

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 and Select Your Application

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

Add WorkOS to your list of authorized domains

Select "OAuth Consent Screen" in the left-hand navigation menu, add workos.com to your list of "Authorized domains", and select "Save".

3

Create Your Application's OAuth Client Credentials

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

Link Your Connection

Add your Google Client ID and Google Client Secret to their respective fields in your Connection's settings.

Select "Update Connection" and your Connection will then be linked and ready to go!

5

Associate a domain with your Connection

To associate a domain, first navigate to your Connection Settings in the Dashboard and click the "New Connection" button.

Then, select "Google OAuth" as your Identity Provider, and enter your enterprise customer's domain for your Domain.

And since you've already configured the Global IdP settings for your Google Connection, your Connection should be Linked. Your Connection's Linked status is indicated by the green badge next to the Connection name.

After that, you're now able to authenticate users from the listed domain using your Google Connection.

Frequently asked questions

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

It’s the same G Suite 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 G Suite OAuth, you can use WorkOS SSO to support other identity providers, all with a single integration.

The G Suite OAuth sign in form displays "Choose an account to continue to workos.com". How can I custom brand this to my application's domain?

To custom brand this domain, we’ll need to give you ownership of your Google Authorized Redirect URI. And the best way to give you ownership over your Google Authorized Redirect URI is to change the root domain from auth.workos.com to a subdomain hosted by you, something like auth.yourapp.com. To do this, we will ask you to set a CNAME record pointing to our DNS server so auth.yourapp.com redirects traffic to our API. Then we will update your Authorized Redirect URI to use auth.yourapp.com instead of auth.workos.com. After this process is complete you should be able to verify that you own the yourapp.com domain. Once ownership of yourapp.com is verified, the domain of the Authorized Redirect URI will be displayed on the G Suite sign in form. Please reach out to support for assistance in implementing this change.

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.