If desired, Looker can perform authentication via Google OAuth, for users that have accounts registered with GSuite.
- Organizations using GSuite can authenticate Looker users via Google accounts.
- Users log 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.
- When enabled, Looker authenticates users only with Google OAuth unless the “alternate login” option is selected (see further instructions below).
A user’s Google avatar appears in the navigation bar instead of the standard user symbol:
The following behaviors might affect your decision to use Google OAuth:
- 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 log 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 via Google OAuth cannot switch to password authentication, even if OAuth is disabled for the Looker instance.
Using Google OAuth requires the following:
- A GSuite account for the organization. The user’s Google account must have first name and last name configured for Looker to authenticate the user with Google OAuth.
- A domain controlled by the organization and registered to the GSuite account.
- Users with email addresses in the domain associated with the Google account.
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 below. Google’s generic description of these steps is here. Further documentation on the Google Dev Console is here.
Go to the Google Cloud Platform 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:
Google displays the New Project page.
Enter a specific, distinguishable name in the Project Name field:
Select your organization name in the Location field.
When Google is done creating your new project, Google returns you to the Google Cloud Platform Console and shows your new project.
In the left menu, select APIs & Services > Credentials:
In the Credentials page, click the down arrow in the Create credentials button, and select OAuth client ID from the drop-down menu:
Google displays the Create OAuth client ID page.
Google displays the OAuth consent screen page:
You can configure this screen for all applications in your project, including both internal and public applications. Google will perform a verification for public applications if any of these are true:
- The application uses Google APIs that use restricted or sensitive scopes.
- The OAuth consent screen includes an application logo.
- The project has exceeded the domain threshold.
When configuring the Looker side for Google OAuth, you have the option to limit access to specific domains.
Looker requires only the default scopes, so no additional scope configuration is required.
Looker does require an entry in the Authorized domains field. Enter the domain of the URL to your Looker instance. For example, if Looker hosts your instance at
https://instance_name.looker.com, the domain is
looker.com. For customer-hosted Looker deployments, enter the domain on which you host Looker.
For information about configuring the Google OAuth consent screen, see Google’s documentation here.
Configure your OAuth consent screen and click Save.
Google returns you to Create OAuth client ID page.
Under Application type, select Web application:
Google displays the rest of the Create OAuth client ID page.
In the Name field, enter a name for your OAuth client ID.
https://. For example:
- If Looker hosts your instance:
- If you have a customer-hosted Looker instance:
- If your Looker instance requires a port number:
In the Authorized redirect URIs field, enter the URL to your Looker instance, followed by
/oauth2callback. For example:
Google displays your client ID and your client secret.
Copy your client ID and your client secret values — you will need them to configure Looker:
Setup on the Looker Side
The steps for enabling Google OAuth on the Looker side are below.
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 Google setup instructions above.
Domains - Your organization’s Google-managed domain name(s). Any Google user in the given domain can log 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 do not control.
Enter Migration Options, which control behavior of the Looker instance during the transition to Google OAuth:
- Alternate login for admins - Lets admins continue logging in with email and password, which is a useful fall-back in case of problems setting up Google OAuth. This setting is recommended and is described further below.
- Merge by email - Converts any existing users with email addresses in the given Domains to use Google OAuth, upon their next login. 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 log in to Looker, consider specifying a default role for new users that limits access appropriately.
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 are not logged into Google, you are prompted to log in and asked for consent to use your Google account information. This flow uses the custom Consent screen settings you used in the Google-side setup.
Upon success, a User Info section displays with your name, email, domain, etc. Presence of this User Info section shows that this user would be successfully authenticated by Looker.
Upon failure, error descriptions appear. Below are some common issues:
- 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.
- Looker URL and/or redirect URL not set up correctly in Google for your Looker.
To save and apply changes, check I have confirmed the configuration above and want to enable applying it globally. Click Update.
After you enable Google authentication, users can authenticate only through Google OAuth. If you did not enable the Merge by email setting for existing accounts, every new Google-authenticated login creates a new Looker user. Existing email/password logins are not usable at the same time that Google authentication is enabled.
To experiment with the full authentication cycle, you can log out of Google and see that Google prompts you to log in again when you attempt to log in to Looker.
In Google you can click on Account in the personal drop-down (next to your email address on the top right of a GSuite 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 above. You can also click Revoke access so that the next time you log 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.
If a user cannot log in, but does not receive an error message, they may have edited their Gsuite account name and deleted either their first or last name. In this situation, the Gsuite account name may still look complete in the Admin console, which may not show the user’s edits. To prevent this issue, Gsuite admins can disable the Allow users to customize this setting option.
Enabling E-mail 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 via e-mail 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
- Go to Add Users from the users panel (/admin/users/new)
- Add the e-mail address(es) you would like to include, and the roles those users should have, which must include a role with the
- Those users are now able to log in via https://instance_name.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 log in. While their accounts still exist, they have no way to access them, and their accounts are effectively orphaned.
This is why, currently, 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.