Connect Your App to Google Workspace

Using Google Social and Enterprise Connections

If you have an existing Google Social Connection for your application and you create a new Google Workspace connection for the same domain, users affiliated with the social connection with now be logged in with the new enterprise connection. This will occur regardless of whether you enable the Google Workspace enterprise connection.

Prerequisites

Before you begin:

• Register your Application with Auth0.

  • Select an appropriate Application Type.
  • Add an Allowed Callback URL of {https://yourApp/callback}.
  • Make sure your Application’s Grant Types include the appropriate flows.

Steps

To connect your application to Google Workspace, you must:

1. Set up your app in Google
2. Create an enterprise connection in Auth0
3. Enable the enterprise connection for your Auth0 Application
4. Test the connection

Google Workspace account

Before proceeding, you will need a valid Google Workspace account and must have your own Google Workspace Organization for which you are an administrator.

Set up your app in Google

To allow users to log in using Google Workspace, you must register your application in the Google developer console.

Before proceeding, you must have already set up your own Google Workspace Organization for which you are an administrator.

Register a new application

To learn how to register a new application with Google, follow Google’s Setting up OAuth 2.0 doc. During this process, Google will generate a Client ID and Client Secret for your application; make note of these.

While setting up your app, be sure to use these settings:

• On the OAuth consent screen, under Authorized domains, add auth0.com.

• When asked to select an application type, choose Web application and set the following parameters:

  Field	Description
  Name	The name of your application.
  Authorized JavaScript origins	https://{yourDomain}
  Authorized redirect URIs	https://{yourDomain}/login/callback

  Find your Auth0 domain name for redirects

  If your Auth0 domain name is not shown above and you are not using our custom domains feature, your domain name is a concatenation of your tenant name, your regional subdomain, and auth0.com, separated by the dot (.) symbol.

  For example, if your tenant name is exampleco-enterprises, and your tenant is in the US region, your Auth0 domain name would be exampleco-enterprises.us.auth0.com and your Redirect URI would be https://exampleco-enterprises.us.auth0.com/login/callback.

  However, if your tenant is in the US region and was created before June 2020, then your Auth0 domain name would be exampleco-enterprises.auth0.com and your Redirect URI would be https://exampleco-enterprises.auth0.com/login/callback.

  If you are using custom domains, your Redirect URI would be https://<YOUR CUSTOM DOMAIN>/login/callback.

If your application requests sensitive OAuth scopes, it may be subject to review by Google.

Enable the Admin SDK Service

If you plan to connect to Google Workspace enterprise domains, you need to enable the Admin SDK Service. To learn how, follow Google’s Enable and disable APIs doc.

Create an enterprise connection in Auth0

The Google Enterprise connection allows Auth0 user profiles to have up to 200 groups. If a user profile has more than 200 groups, these results may not be shown.

Google Workspace does not enforce group name uniqueness. To access extended group properties, such as unique IDs and email addresses, review the Using Identity Provider Tokens from Google section below. If you use Google groups for authorization, you must secure the workspace to prevent unauthorized users from modifying groups.

Next, you will need to create and configure a Google Workspace Enterprise Connection in Auth0. Make sure you have the Client ID and Client Secret generated when you set up your app in the Google developer console.

1. Navigate to Auth0 Dashboard > Authentication > Enterprise, locate Google Workspace, and click its +.

   

2. Enter details for your connection, and select Create:

   Field	Description
   Connection name	Logical identifier for your connection; it must be unique for your tenant. Once set, this name can’t be changed.
   Google Workspace Domain	Google Workspace domain name for your organization.
   Client ID	Unique identifier for your registered Google application. Enter the saved value of the Client ID for the app you just registered in the Google developer console.
   Client Secret	String used to gain access to your registered Google application. Enter the saved value of the Client Secret for the app you just registered in the Google developer console.
   Attributes	Basic attributes for the signed-in user that your app can access. Indicates how much information you want stored in the Auth0 User Profile. Options include: Basic Profile (email, email verified flag) and Extended Profile (name, public profile URL, photo, gender, birthdate, country, language, and timezone).
   Extended Attributes (optional)	Extended attributes for the signed-in user that your app can access. Options include: Groups (distribution list(s) to which the user belongs, including the Extended Group Attributes Format option that retrieves the group name, group email address, and the unique group ID), Is Domain Administrator (indicates whether the user is a domain administrator), Is Account Suspended (indicates whether the user’s account is suspended), and Agreed to Terms (indicates whether the user has agreed to the terms of service).
   Auth0 APIs (optional)	When Enable Users API is selected, indicates that you require the ability to make calls to the Google Directory API.
   Auth0 User ID (optional)	By default, the Auth0 user_id maps to email. By enabling Use ID instead of Email for Auth0 User ID, user_id instead maps to id. This can only be set for new connections and cannot be changed once configured.
   Sync user profile attributes at each login	When enabled, Auth0 automatically syncs user profile data with each user login, thereby ensuring that changes made in the connection source are automatically updated in Auth0.

   

3. If you have appropriate administrative permissions to configure your Google Workspace settings so you can use Google’s Admin APIs, then click Continue. Otherwise, provide the given URL to your administrator so that they can adjust the required settings.

4. On the Login Experience tab, you can configure how users log in with this connection.

   Field	Description
   Home Realm Discovery	Compares a user’s email domain with the provided identity provider domains. For more information, read Configure Identifier First Authentication
   Display connection button	This option displays the following choices to customize your application’s connection button.
   Button display name (Optional)	Text used to customize the login button for Universal Login. When set the button reads: “Continue with {Button display name}”.
   Button logo URL (Optional)	URL of image used to customize the login button for Universal Login. When set, the Universal Login login button displays the image as a 20px by 20px square.

   Optional fields are available with Universal Login only. Customers using Classic Login will not see the Add button, Button display name, or Button logo URL.

Work with the connection

Enable the enterprise connection for your Auth0 application

To use your new AD connection, you must first enable the connection for your Auth0 Applications.

Test the connection

Now you’re ready to test your connection.

Request Refresh Tokens from Google

Google always returns an Access Token, which is stored in the user profile. If you add access_type=offline&approval_prompt=force to the authorization request, Auth0 will forward these parameters to Google. Google will then return a Refresh Token, which will also be stored in the user profile.

Use Identity Provider Tokens from Google

To retrieve additional user and group details beyond what Auth0 retrieves by default, you can use the access tokens returned from Google to call Google’s APIs. To securely access these tokens, follow the guidelines provided in Identity Provider Access Tokens.

For Google Workspace, Auth0 stores access tokens and refresh tokens on the user object for individual users and on the connection object for workspace admins.

To retrieve all extended group properties for a user with Google’s Directory Admin API, navigate to the Goolgle Workspace connection in your Auth0 Dashboard and enable the Groups extended attribute. Then, complete administrator consent using the Setup tab.

After these steps are complete, use the Get a connection endpoint of the Auth0 Management API to retrieve the admin access token stored on the connection object. You can then use this token to call Google’s Manage Groups endpoint.

Example call:

curl -H "Authorization: OAuth {admin_access_token}" https://admin.googleapis.com/admin/directory/v1/groups\?userKey={user_key}

Validate authentication with Actions

You can use post-login Actions to validate whether authentication events are coming from legitimate users who are members of a Google organization. This can help mitigate potential vulnerability by preventing unauthorized access to your applications after users are no longer part of your organization.

To verify legitimate Google authentications, use post-login Actions to validate the idp_tenant_domain claim associated with the user and ensure the value matches the expected organization for that user.

You can only verify idp_tenant_domain for users who authenticate with the following connection types:

• Google Social
• Google Workspace
• Google OIDC

Example

The following example demonstrates how you can validate the idp_tenant_domain using post-login Actions.

exports.onExecutePostLogin = async (event, api) => {

 // Example to block social accounts
 if (event.connection.strategy === 'google-oauth2' 
 && !event.user.idp_tenant_domain) // Non-organization Accounts
 {
   api.access.deny('Account not allowed for login');
 }

 // Example to only permit allowlisted organization accounts
 if (event.connection.strategy === 'google-oauth2' 
 && event.user.idp_tenant_domain != "allowedOrganization.com") 
 {
   api.access.deny('Your Google Organization is not allowed to login');
 }

};

Reauthorize existing connections

If a Google Workspace admin is deleted, any Google Workspace Enterprise connections they have set up and authorized will need to be reauthorized by a new Google Workspace admin to avoid login failures. This can be done by having the new admin use the link in the Setup tab for the Google Workspace Enterprise connection.

Next Steps

• Integrate with Auth0 using one of our libraries
• Integrate with Auth0 using our Authentication API
• Read more about the authentication flow
• Pass additional parameters to the Identity Provider
• Re-prompt users for permissions