Admin settings - Google authentication

The Google Authentication page in the Authentication section of the Admin menu lets you set up Google OAuth on the Looker side.

Feature overview

Looker can perform authentication using Google OAuth for users that have accounts registered with Google Google Workspace.

Organizations using Google Google Workspace can authenticate Looker users who have Google Accounts.
Users sign in to Looker by authenticating with their Google Account.
New Google Accounts automatically get access to Looker. No need to separately invite users to Looker. You set the default role for new users, which can limit their access to functionality and data.
Organizations can configure Google Group mirroring to automatically assign Looker roles and groups based on Google Groups membership.
When enabled, Looker authenticates users only with Google OAuth unless the "alternate login" option is selected (see the following section on Enabling email logins while Google Auth is enabled).
A user's Google avatar appears in the navigation bar instead of the standard user symbol.

When enabling Google OAuth, the Looker instance can merge existing user accounts with the Google-registered domain, but only for accounts whose email address matches the domain. All other non-admin accounts will lose the ability to sign in.
All users in the specified domain get access to the Looker instance.
Permissions for new Google users defaults to basic access for a specified list of models (which could, optionally, be access to zero models). Permissions can be updated by an admin after account creation.
New Looker accounts that authenticate using Google OAuth cannot switch to password authentication, even if OAuth is disabled for the Looker instance.

Preliminary requirements

Using Google OAuth requires the following:

A Google Workspace account for the organization.
A domain controlled by the organization and registered to the Google Google Workspace account.
Users with email addresses in the domain associated with the Google Account.
Each user must have a managed user account in Google Google Workspace. To find and migrate any users with unmanaged user accounts, use the Transfer tool for unmanaged users.

To use Google Group mirroring, the following additional requirements apply:

In the Google Cloud project that contains your OAuth client, the Cloud Identity API (cloudidentity.googleapis.com) must be enabled.
For customer-hosted Looker instances, the instance host must have outbound internet access over HTTPS (cloudidentity.googleapis.com:443).
Users must have the VIEW_MEMBERSHIP permission on the Google Groups that they belong to. In Google Groups settings, set the Who can view members field to Group members.
Google Group mirroring is not supported for Looker instances that are in FIPS-compliant mode.

Enabling authentication with Google OAuth

Enabling authentication with Google OAuth requires an administrator to perform steps both on the Google side, and on the Looker side, as described in the following sections.

Setup on the Google side

The steps for enabling Google OAuth on the Google side are described in this section. The generic description of these steps is on the Google support page on setting up OAuth 2.0. You can also refer to Google Cloud console Help documentation.

Go to the Google Cloud console.
Click the down arrow in the Select a project drop-down. You may see the name of an existing project in the drop-down; click the down arrow regardless, and it will take you to the option to create a new project.
In the Select a project page, click New Project.

The Google Cloud console displays the New Project page.
Fill out the information on the New Project page and click Create.

When the Google Cloud console is done creating your new project, Google returns you to the Google Cloud console and shows your new project.
Optional: If you plan to use Google Group mirroring, enable the Cloud Identity API in your Google Cloud project. Enabling this API makes the https://www.googleapis.com/auth/cloud-identity.groups.readonly scope visible when you configure the OAuth consent screen. You must have the Service Usage Admin (roles/serviceusage.serviceUsageAdmin) Identity and Access Management (IAM) role to enable APIs.

Enable the API
In the left menu, select APIs & Services > Credentials.
On the Credentials page, click the Create credentials button, and select OAuth client ID from the drop-down menu.

The Google Cloud console displays the Create OAuth client ID page.
The Google Cloud console requires that you configure an OAuth consent screen, which lets your users choose how to grant access to their private data and provides a link to your organization's terms of service and privacy policy. Click Configure consent screen. (If you have configured OAuth consent for a previous project, you won't see this option, and you can skip to step 13.)

The Google Cloud console displays the OAuth consent screen page.
Enter the domain of your Looker instance in the Authorized domains field. For example, if Looker hosts your instance at https://mycompany.looker.com, the domain is looker.com. For customer-hosted Looker deployments, enter the domain on which you host Looker.
Configure your OAuth consent screen and click Save and Continue.

Note: For information about configuring the Google OAuth consent screen, see the Configure OAuth Google Workspace page.
On the Scopes page, configure scopes as follows:
- If you plan to use Google Group mirroring, click Add or remove scopes. Find the https://www.googleapis.com/auth/cloud-identity.groups.readonly scope, select the checkbox next to it, and click Update. If you don't see this scope, verify that you enabled the Cloud Identity API in your Google Cloud project.
- If you don't plan to use Google Group mirroring, no additional scope configuration is required.
Click Save and Continue.

Caution: If the User Type field in your OAuth client is set to External, you must complete restricted scope verification for the OAuth app when you add the sensitive https://www.googleapis.com/auth/cloud-identity.groups.readonly scope. Until the OAuth app has been verified by Google, users will be able to sign in, but they will see a warning message during the sign-in process because the Cloud Identity API is a sensitive scope.
On the Summary page, click Back to Dashboard.

The Google Cloud console returns you to the Create OAuth client ID page.
Under Application type, select Web application.
In the Name field, enter a name for your OAuth client ID.
In the Authorized JavaScript origins field, enter the URL to your Looker instance, including the https://. For example:
- If Looker hosts your instance: https://mycompany.looker.com
- If you have a customer-hosted Looker instance: https://looker.mycompany.com
- If your Looker instance requires a port number: https://looker.mycompany.com:9999
In the Authorized redirect URIs field, enter the URL to your Looker instance, followed by /oauth2callback. For example: https://mycompany.looker.com/oauth2callback or https://looker.mycompany.com:9999/oauth2callback.
Click Create.
Copy your client ID and your client secret values — you will need them to configure Looker.

Setup on the Looker side

To enable Google OAuth on the Looker side, follow these steps.

From the Looker application, while logged in as an administrator, click the Admin drop-down to open the Admin menu.
Under the Authentication group, click Google. Looker displays the Google Authentication page.
Click Enabled to display and edit Google OAuth settings. (This does not immediately enable Google authentication; you must confirm your choice later).
Enter your Google Auth Settings.
- Client ID and Client Secret - Copy and paste these values from the Google OAuth client page, as discussed in the previous Google setup instructions.
- Domains - Your organization's Google-managed domain name(s). Any Google user in the given domain can sign in to your Looker instance. If you control multiple Google domains you can enter them separated by commas.
Warning: Only enter Google domains controlled by your organization. Entering any other domain could open access to users of a domain you don't control.
Enter Migration Options, which control behavior of the Looker instance during the transition to Google OAuth.
- Alternate login for admins and specified users - Lets administrators and specified users continue logging in with email and password. This setting enables a critical fallback method to prevent a complete lockout if the Google Cloud project that's hosting the Looker OAuth client is deleted or disabled (which can result in a 401 deleted_client error even after project restoration), or if Google OAuth fails for other reasons. This setting is highly recommended and is described further in Enabling email logins while Google Auth is enabled.
- Merge Users Using - Converts existing users who have email addresses in the specified Domains to use Google OAuth upon their next login (such as Looker Email/Password). This setting is recommended.
- Roles for new users - Specifies the functionality and model access that new, non-admin users have. This list can be updated later. If left blank, new Google-authenticated users will have limited functionality inside the Looker platform until an admin adds a role to their account. Since all users within your Google domain will be able to sign in to Looker, consider specifying a default role for new users that limits access appropriately.
Note: When Mirror Google Groups is enabled, the Roles for new users setting is hidden. Looker removes roles that were previously assigned by Roles for new users on each user's next login and replaces them with the roles that were assigned through Mirror Google Groups.
Configure Groups & Roles to optionally mirror Google Groups into Looker groups and assign roles automatically:

If you have managed Google Groups, Looker can create Looker groups that mirror the membership of your Google Groups, which means that you don't have to set up users in Looker directly, but can manage user access by managing the membership of the Google Groups. Additionally, you can use Looker groups to assign roles to group members, set content access controls, control feature and data access, and assign user attributes.

Note: Google OAuth group mirroring isn't supported for Looker instances that are in FIPS-compliant mode.
Caution: For customer-hosted Looker instances, the host server must have outbound internet access to the Cloud Identity API over HTTPS (cloudidentity.googleapis.com:443). Customer-hosted instances without outbound internet access cannot use Google Group mirroring.

For group mirroring to function correctly, users must have the VIEW_MEMBERSHIP permission on the Google Groups that they belong to, which lets Looker check their group memberships at sign-in. To grant this permission in Google Groups settings, set the Who can view members field to Group members.

To enable group mirroring, follow these steps:
1. Turn on the Mirror Google Groups toggle.
2. Click Manage Groups to open the group mapping configuration.
3. Complete the following fields for each Google Group that you want to mirror:
  - Looker Group Name: Enter a name for the Looker group. This name appears on the Groups page within Looker.
  - Google Group ID: Enter the name or email address of the Google Group to mirror.
  - Roles: Select one or more Looker roles to assign to members of the group.
Looker creates one Looker group for every Google Group that you add to the configuration. You can view those groups on the Groups page in Looker.

Note: Looker fetches only direct group memberships of the user. Any transitive or hierarchical group memberships won't work.

Looker applies the mirrored Looker groups (and any associated roles and access) when users sign in to the Looker instance. Changes to group memberships in Google Groups are updated upon each user's next login.

Mirror Google Groups

After you configure Google Group mirroring, you can edit or disable mirrored groups, and configure advanced role management options as described in the following sections.

Editing mirrored groups

When you make changes to a Google Groups membership, those changes are automatically propagated to the mirrored Looker group's membership and validated at the time of each user's next login.

If you edit the Looker Group Name or Role assigned to a group on the Google Authentication page, this changes how the mirrored group appears on the Groups page or the roles assigned to the group, but it doesn't change the group members.

If you change the name or email in the Google Group ID field to a new Google Group ID, that changes the members of the mirrored Looker group to the members of the new Google Group, while maintaining the group name and roles defined on the Google Authentication page.

Looker applies any edits that you make to a mirrored group to users of that group when they next sign in to Looker.

Disabling mirrored groups

If you want to stop mirroring your Google Groups within Looker, turn off the Mirror Google Groups toggle on the Google Authentication page. Disabling the toggle results in the following behavior:

Any mirrored Google group with no users is deleted immediately.
Any mirrored Google group that does contain users is marked as orphaned. Users can no longer be added to or removed from orphaned groups. If no users from an orphaned group log in within 31 days, the group is deleted.

Advanced role management

If the Mirror Google Groups toggle is enabled, the Advanced Role Management section displays options that determine how strictly Looker admins can configure Looker groups and users who have been mirrored from Google.

If you want your Looker group and user configuration to strictly match your Google Groups configuration, select all the Advanced Role Management options. When all options are enabled, Looker admins cannot modify mirrored group memberships directly and can only assign roles to users through Google Groups.

If you want more flexibility to customize groups within Looker, leave these options cleared. Your Looker groups will still mirror your Google Groups configuration, but you can perform additional group and user management within Looker, such as adding Google users to built-in Looker groups or assigning roles directly to Google users.

The Advanced Role Management section contains the following options:

Prevent individual Google users from receiving direct roles: Turning this option on prevents Looker admins from assigning Looker roles directly to Google users. Google users receive roles only through their group memberships. If Google users are allowed membership in built-in (not mirrored) Looker groups, they can still inherit roles from both mirrored Google Groups and built-in Looker groups. Any Google users who were previously assigned roles directly will have those roles removed when they next log in.

Caution: If you enable Prevent individual Google users from receiving direct roles on a Looker (original) instance, any administrator who signs in with Google OAuth will lose their directly assigned Admin role upon their next login unless they are granted the Admin role through a mirrored Google Group, or sign in using Alternate login for admins. Before turning on this option, map an admin Google Group to the Admin role, or verify that Alternate login for admins is enabled.
Prevent direct membership in non-Google groups: This option prevents Looker admins from adding members of mirrored groups directly to built-in Looker groups that are not part of the mirrored group configuration on the Google Authentication page.

If this option is selected, any Google users who were previously assigned to built-in Looker groups will be removed from those groups when they next log in.

If this option is cleared, Looker admins can add Google users directly to built-in Looker groups.
Prevent role inheritance from non-Google groups: This option prevents members of mirrored groups from inheriting roles from built-in Looker groups. If mirrored Google Groups are allowed to be members of built-in Looker groups, Google users may retain membership in built-in Looker groups, but any Google users who previously inherited roles from a built-in group will lose those roles when they next sign in.

If this option is cleared, mirrored groups or Google users who are added as members of a built-in Looker group will inherit the roles assigned to that built-in group.
Auth Requires Role: If this option is on, Google users must have an assigned Looker role. If this option is on, Looker requires Google users to have an assigned Looker role in order to sign in to Looker at all.

If this option is cleared, Google users can authenticate to Looker even if they have no role assigned. A user with no assigned role won't be able to see data or take actions in Looker, but they will be able to sign in.

Test User Authentication

Click Test Google Authentication to use the current settings and attempt to authenticate the current browser in a new window. This action does not save the current settings or apply them to the Looker instance.

If you aren't logged in to Google, you are prompted to sign in and asked for consent to use your Google Account information. This flow uses the custom Consent screen settings that you used in the Google-side setup.

Upon success, a User Info section displays with your name, email, and domain, along with any mirrored Google Groups detected for your account. Presence of this User Info section shows that this user would be successfully authenticated by Looker.

Upon failure, error descriptions appear. Some common issues include the following:
- Miscopied Client ID or Client Secret. These must be carefully copied and pasted in full.
- User is out of domain. If you see a Person Info section, but no User Info, it is probably because the user is not in the domain you specified. This shows that the person has authenticated themselves to Google correctly, but they are not using a Google Account that you have chosen to allow into your Looker instance.
- A Looker URL or redirect URL is not set up correctly in Google for your Looker instance.
- If Google Groups fail to load, verify that the Cloud Identity API is enabled in your Google Cloud project, that the https://www.googleapis.com/auth/cloud-identity.groups.readonly scope was added, and that the user has VIEW_MEMBERSHIP permissions on their Google Groups.
To save and apply changes, select I have confirmed the configuration above and want to enable applying it globally. Click Update.

Configuring Google authentication using the API

Administrators can read and update Google authentication settings and group role mappings programmatically by using the google_config endpoints in the Looker API. For more information, see the Looker API reference.

Tips

To experiment with the full authentication cycle, you can log out of Google and see that Google prompts you to sign in again when you attempt to sign in to Looker.
In Google you can click Account in the personal drop-down (next to your email address on the top right of a Google Google Workspace page) to manage your personal account.

On that management page there is a Security tab with an Account Permissions section. Clicking on Apps and websites View all lets you (as a user) see and manage the services and apps to which you have granted permissions.

Clicking on the Looker permissions that you granted in order to log on shows the details that users see in the consent screen that you customized previously. You can also click Revoke access so that the next time you sign in to Looker (or test authorization) you will be re-prompted with the consent screen. You can use this workflow to help you customize your consent screen and view what users will see.

Troubleshooting

To help troubleshoot authentication issues, check the User Activity dashboard in System Activity. This dashboard has tiles that display recent login failures and includes the authentication method that was used, the error message that was returned, and the time of the attempt.

If a user's attempt to sign in fails, first make sure the user has both a first name and a last name in their Google Accounts. If the user has deleted either their first name or their last name from their Google Account, Looker may be unable to authenticate the user with Google OAuth.
If a user's attempt to sign in fails, and Looker displays an error such as User not in the authorized domain, check the hd field of the JSON response. If the hd field contains a domain, make sure that the domain is registered to your Google Google Workspace account. If the hd field is empty, use the Transfer tool for unmanaged users to invite the user to convert their account to a managed account within your domain.
If a user's attempt to sign in fails, but Looker does not display an error message, the user may have edited their Google Google Workspace account name and deleted either their first or last name. In this situation, the Google Google Workspace account name may still look complete in the Admin console, which may not show the user's edits. To prevent this issue, Google Google Workspace admins can disable the Allow users to customize this setting option.
If Google authentication returns a 401 deleted_client error, this error indicates that the Google Cloud project that's hosting the Looker OAuth client has been deleted or disabled. Even if the Google Cloud project is subsequently restored, the OAuth client may continue to fail with the deleted_client error, resulting in a complete login lockout for all users. If Google authentication is the only enabled authentication method, this lockout prevents access even for administrators.

To prevent complete lockout in the event of an OAuth client deletion or failure, you must enable the Alternate login for admins setting. This setting ensures that administrators have a fallback login method to access the Looker instance and update authentication settings.

Enabling email logins while Google Auth is enabled

New Google Accounts automatically get access to Looker, so there is no need to add users that are in your Google Domain.

To add a user with an email address that is not in your Google Domain:

Enable the Alternate login for admins and specified users option on the Google Auth page
Create or modify an existing user role to add the login_special_email permission
Go to Add Users from the users panel (/admin/users/new)
Add the email address(es) you would like to include, and the roles those users should have, which must include a role with the login_special_email permission
Those users are now able to sign in using https://mycompany.looker.com/login/email (hidden URL)

Disabling Google Auth once it has been enabled

If you'd like to disable Google Authentication for your Looker instance after it has already been enabled, there are some things to think about:

Users who were created before Google Authentication was added, and already setup a normal email login and password, will still function.
Users who were created after Google Authentication was added will no longer be able to sign in. While their accounts still exist, they have no way to access them, and their accounts are effectively orphaned.

This is why we suggest avoiding this route. If you must go down this path there may be a method to fix the orphaned accounts by using the Looker API. Reach out to Looker Support for additional guidance.