Google Authentication

On this Page
Docs Menu

Feature Overview

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

  • Organizations using Google Apps for Work can authenticate Looker users via Google accounts.
  • Users log into Looker by authenticating with their Google account.
  • New Google accounts automatically get access to Looker. No need to separately invite users to Looker.
  • 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.

Note the following behaviors that 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 login.
  • 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.

Preliminary Requirements

Using Google OAuth requires the following:

  • A Google Apps for Work account for the organization.
  • A domain controlled by the organization and registered to the Google Apps for Work 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 are described here, in the section titled Setting up OAuth 2.0. Further documentation on the Google Dev Console is here.

  1. Go to the Google dev console.

  2. Click the Create Project button to create a new project for Looker.

  3. Enter a specific, distinguishable name in the PROJECT NAME field.

    Note that the new project is not available immediately.

  4. After Google finishes creating the new project, click on your project in the list to get to the Project Dashboard for the project.

  5. Click APIS & AUTH in the left sidebar, then click sub-item APIs to get to the list of enabled APIs for the project.

  6. Turn on Google+ API. (The list has other APIs turned on by default. You can leave them on or turn them off as you choose. Looker's Google OAuth authentication uses only the Google+ API option)

  7. Click Credentials in the left sidebar.

  8. Click the Create new Client ID button (in the OAuth section at the top). The Create Client ID dialog appears.

  9. Enter the following information in to the dialog:

  • APPLICATION TYPE: Web Application
  • AUTHORIZED JAVASCRIPT ORIGINS: Enter the path to your Looker instance as you would in a browser. This must be an https URL.

    • If Looker hosts your instance this URL will look like https://yourcompany.looker.com.
    • If you host Looker yourself (on-premise) the URL will typically look like https://looker.yourcompany.com or https://looker.yourcompany.com:9999 if your Looker instance requires a port number.
  • AUTHORIZED REDIRECT URI: The dialog automatically populates this field. It must end with /oauth2callback. For example: https://yourcompany.looker.com/oauth2callback

  1. Click Create ClientID to finalize creation of the new ID and return to the Credentials page, which now includes your new Client ID for web application. When configuring Looker settings, you need the CLIENT ID and CLIENT SECRET items on this page.

  2. Click Consent screen in the left-hand navigation. This page allows you to customize the information that end-users see when they authorize Looker to use their Google account for login, such as custom text and logo. You can customize this information to help users understand that you authorize your organization's Looker instance to use the user's id information. Fields of special interest include: PRODUCT NAME, EMAIL ADDRESS, LOGO

  3. Customize the Consent Screen details as appropriate for your organization. Click Save when done to return to the Credentials page.

  4. Leave the Credentials page open so you can use information on this page when configuring Looker settings. Proceed to configure settings on the Looker side.

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 Security group, click Google Authentication. The Google Integration Settings page displays. (Note that Google Authentication is a license-enabled feature. The Google Authentication 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:

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

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

    • Alternate login for admins - Allows admins to 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 what models new, non-admin users have access to. 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.
  6. 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 will be 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.
  7. 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 will create a new Looker user. Existing email/password logins will not be 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 will allow you (as a user) to 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 will show the details that users will 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

To add a user via e-mail address (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 will now be 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:

  • 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 login. While their accounts will still exist, they will 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.

Still have questions?
Go to Discourse - or - Email Support
Top