Connect Google OAuth
Learn How to configure a connection to Google Workspace 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.
Start by logging in to your WorkOS dashboard and browse to the 'Organizations' tab on the left hand navigation bar.
Select the organization you'd like to configure a Google OAuth Connection for, and add a connection under 'Single Sign-On Connections'.
You'll be prompted to enter the Organization's Domain and additionally you'll want to select "Google OAuth" from the Identify Provider dropdown. Once this is filled out, click "Create Connection".
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.
Simply open your Developer Dashboard, browse to the 'Configuration' tab on the left hand nav bar. Scroll down to the 'Google Settings' and you'll see the Redirect URI as well as the fields you'll populate later with information from Google.
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
You should already see a list of connected domains in the Google OAuth Connection, including the one you inputted in the 'Introduction' step above.
However, should you need to make any edits, like adding or removing, you can do this by clicking on 'Edit Domains'.
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 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.
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 Google 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.