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.

Simply open your WorkOS 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.

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

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!

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 be ready to go!

After that, you're now able to authenticate users with Google OAuth. Provide the provider parameter when authenticating Google OAuth users, because Google OAuth does not take a user’s domain into account when logging in with a “Sign in with Google” button. You will use theprovider 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.

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". Note: This button will only appear if your environment has a valid Google OAuth configuration and has not already setup a 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, you will see 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.

Save your new Google OAuth configuration by clicking "Save custom Google OAuth settings".

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.