Note: Setting up Google authentication inLooker (Google Cloud core) is covered on theCreate OAuth authorization credentials for a Looker (Google Cloud core) instance and theUse Google OAuth for Looker (Google Cloud core) user authentication documentation pages.

TheGoogle Authentication page in theAuthentication section of theAdmin menu lets you set up Google OAuth on the Looker side.

Note: If you have a permission that provides access to only select pages in the Admin panel, such asmanage_schedules,manage_themes, orsee_admin, but you don't have theAdmin role, the page or pages that are described here may not be visible to you in the Admin panel.

Feature overview

Looker can perform authentication usingGoogle 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.
• When enabled, Looker authenticates usersonly with Google OAuthunless the "alternate login" option is selected (see the following section onEnabling email logins while Google Auth is enabled).
• A user's Google avatar appears in the navigation bar instead of the standard user symbol.

Warning: 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 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:

• AGoogle 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 amanaged user account in Google Google Workspace. To find and migrate any users with unmanaged user accounts, use theTransfer tool for unmanaged users.

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 onsetting up OAuth 2.0. You can also refer toGoogle Cloud console Help documentation.

1. Go to theGoogle Cloud console.

2. Click the down arrow in theSelect 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.

3. In theSelect a project page, clickNew Project.

   The Google Cloud console displays theNew Project page.

4. Fill out the information on theNew Project page and clickCreate.

   When the Google Cloud console is done creating your new project, Google returns you to the Google Cloud console and shows your new project.

5. In the left menu, selectAPIs & Services > Credentials.

6. On theCredentials page, click theCreate credentials button, and selectOAuth client ID from the drop-down menu.

   The Google Cloud console displays theCreate OAuth client ID page.

7. The Google Cloud console requires that you configure anOAuth 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. ClickConfigure 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 theOAuth consent screen page.

8. Enter the domain of your Looker instance in theAuthorized domains field. For example, if Looker hosts your instance athttps://mycompany.looker.com, the domain islooker.com. For customer-hosted Looker deployments, enter the domain on which you host Looker.

9. Configure your OAuth consent screen and clickSave and Continue.

   Note: For information about configuring the GoogleOAuth consent screen, see theConfigure OAuth Google Workspace page.

10. On theScopes page, clickSave and Continue. No additional scope configuration is required.

11. On theSummary page, clickBack to Dashboard.

    The Google Cloud console returns you to theCreate OAuth client ID page.

12. UnderApplication type, selectWeb application.

13. In theName field, enter a name for your OAuth client ID.

14. In theAuthorized JavaScript origins field, enter the URL to your Looker instance, including thehttps://. 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

15. In theAuthorized redirect URIs field, enter the URL to your Looker instance, followed by/oauth2callback. For example:https://mycompany.looker.com/oauth2callback orhttps://looker.mycompany.com:9999/oauth2callback.

16. ClickCreate.

17. Copy yourclient ID and yourclient secret values — you will need them to configure Looker.

Setup on the Looker side

Note: Google Group mirroring is only available when using OAuth withLooker (Google Cloud core)

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

1. From the Looker application, while logged in as an administrator, click theAdmin drop-down to open theAdmin menu.

2. Under theAuthentication group, clickGoogle. Looker displays theGoogle Authentication page.

3. ClickEnabled to display and edit Google OAuth settings. (This does not immediately enable Google authentication; you must confirm your choice later).

4. Enter yourGoogle Auth Settings.

   • Client ID and Client Secret - Copy and paste these values from the GoogleOAuth 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.

5. EnterMigration 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 inEnabling email logins while Google Auth is enabled.
   • Merge by email - Converts any existing users with email addresses in the givenDomains 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 sign in to Looker, consider specifying a default role for new users that limits access appropriately.

6. ClickTest Google Authentication to use the current settings and attempt to authenticate the current browser in a new window. This actiondoes not save the current settings or apply them to the Looker instance.

   If you are not logged into Google, you are prompted to sign in and asked for consent to use your Google Account information. This flow uses the customConsent screen settings you used in the Google-side setup.

   Upon success, aUser Info section displays with your name, email, and domain. Presence of thisUser 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 aPerson Info section, but noUser 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.

7. To save and apply changes, checkI have confirmed the configuration above and want to enable applying it globally. ClickUpdate.

Note: After you enable Google authentication, users can authenticateonly through Google OAuth. If you did not enable theMerge by email setting for existing accounts, every new Google-authenticated login creates a new Looker user. Existing email and password logins are not usable at the same time that Google authentication is enabled.

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 clickAccount 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 aSecurity tab with anAccount Permissions section. Clicking onApps and websitesView 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 clickRevoke 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 theUser 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 asUser not in the authorized domain, check thehd field of the JSON response. If thehd field contains a domain, make sure that the domain is registered to your Google Google Workspace account. If thehd field is empty, use theTransfer 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 theAllow users to customize this setting option.

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:

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

Note: If a user has authenticated into the Looker instance using only Google, you can enable alternate login only by using the Looker API. To learn how to enable alternate login using the Looker API, see theEnabling the alternate login option documentation page.

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 createdbefore Google Authentication was added, and already setup a normal email login and password, will still function.
• Users who were createdafter 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.