Connect Google OAuth
Learn How to configure a connection to Google Workspace via OAuth
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.
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:
Log in to the Google Cloud Platform Console Dashboard. Select your application's project from the project selection dropdown menu in the navigation bar.
2Select your application
Select "OAuth Consent Screen" in the left-hand navigation menu, add workos.com to your list of "Authorized domains", and select "Save".
3Enter Setup Instructions
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!
4Obtain Identity Provider Details
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!
5Associate a domain with your Connection
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.
Frequently asked questions
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