User Guide Help Center Documentation User Forums Training
Looker
Google Authentication

Feature Overview

If desired, Looker can perform authentication via Google OAuth, for users that have accounts registered with Google for Work.

A user’s Google avatar appears in the navigation bar instead of the standard user symbol.

Note the following behaviors that might affect your decision to use Google OAuth:

Preliminary Requirements

Using Google OAuth requires the following:

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 are described here. Further documentation on the Google Dev Console is here.

  1. Go to the Google API console.

  2. Ensure that the organization field is set to your organization:

  3. Click Create Project.

    Google displays the New Project page.

  4. Enter a specific, distinguishable name in the Project Name field:

  5. Click Create.

    When Google is done creating your new project, Google returns you to the Manage Resources page and shows your new project.

  6. Click on your new project:

    Google displays the IAM page:

  7. Click the menu button (three horizontal lines) in the top left corner, and then select APIs & Services > Library:

    Google displays the API library:

  8. Find and click on the Google+ API tile:

    Google displays the Google+ API enablement screen.

  9. Click Enable:

    Google displays the Google+ API page.

  10. In the left menu, select Credentials, and from the Create credentials drop-down menu, select OAuth client ID:

    Google displays the Create client ID page.

  11. Google requires you configure an OAuth consent screen. Click Configure consent screen. (Note, if you have configured OAuth consent for a previous project, you will not see this option, and you can skip to step 13.)

    Google displays the OAuth consent screen page.

    This page lets you customize the information that end-users see when they authorize Looker to use their Google account for login. Google requires you enter values in the Email address and Product name shown to users fields. You can optionally enter URLs to provide users a homepage, logo, privacy policy, or a terms of service document.

  12. Configure your OAuth consent screen and click Save:

    Google returns you to Create Client ID page.

  13. Select Web application:

  14. In the Name field, enter a name for your OAuth client ID:

  15. In the Authorized JavaScript origins field, enter the URL to your Looker instance, including the https://. For example:

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

  2. Click Create.

    Google displays your client ID and your client secret:

  3. Copy your client ID and your client secret values — you will need them to configure Looker:

  4. Click OK.

Setup on the Looker Side

The steps for enabling Google OAuth on the Looker side are below.

  1. From the Looker application, while logged in as an administrator, click the Admin button to open the Admin page.

  2. Under the Authentication group, click Google. Looker displays the Google Authentication page:

    (Note that Google Authentication is a license-enabled feature. The Google option appears only if the feature is enabled on your organization’s Looker license. Contact support@looker.com for details).

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

  4. Enter Google Auth Settings:

  1. Enter Migration Options, which control behavior of the Looker instance during the transition to Google OAuth:

  1. 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 login 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:

    • Mis-copied 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 in 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 setup correctly in Google for your looker.
  2. To save and apply changes, click Update.

    NOTE: 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.

Tips

  1. To experiment with the full authentication cycle, you can logout of Google and see that Google prompts you to re-login when you attempt to log into Looker.

  2. In Google you can click on Account in the personal drop down (next to your email address on the top-right of a Google Apps 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 login 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.

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:

  1. Enable the Alternate login for admins and specified users option on the Google Auth page
  2. Create or modify an existing user role to add the login_special_email permission
  3. Go to Add Users from the users panel (/admin/users/new)
  4. 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 login_special_email permission
  5. Those users are now able to log in via 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:

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.

Top