Connect G Suite OAuth
Learn How to configure a connection to Google G Suite via OAuth
Introduction
Each SSO Identity Provider requires specific information to create and configure a new Connection. Often, the information required to create a Connection will differ by Identity Provider.
To create a Google OAuth Connection, 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. It's readily available in your Connection's Settings in Developer Dashboard.

3
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!

5

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