User Guide Getting Started Help Center Documentation Community Training
OpenID Connect Authentication


Companies use different OpenID Connect Providers (OPs), such as Okta or OneLogin, to coordinate with OpenID Connect. The terms used in the following setup instructions and in the Looker UI may not directly match those used by your OP. For clarification during setup, contact your internal OpenID Connect or authentication team or reach out to Looker Support.

You can configure Looker to authenticate users using the OpenID Connect protocol. This page includes instructions for linking OpenID Connect groups to Looker roles and permissions.

Planning Considerations

Steps on Your OpenID Connect Provider

You need to:

Setting Up Looker on Your OP

Your OpenID Connect Provider (OP) will need to know the URL of your Looker instance. Your OP may call this the “Redirect URI” or “Login Redirect URI”, among other names. On your OP’s web site, provide your OP with the URL where you typically access your Looker instance in a browser, followed by /openidconnect. For example,

Getting Information from Your OP

To configure Looker for OpenID Connect authentication, you will need the following information from your OP:

Many OPs provide information about configuring OpenID Connect in the form of a discovery document. If so, is a convenient way to gather some or all of the information you will need to configure Looker for OpenID Connect. If you do not have access to a discovery document, you will need to obtain the necessary information from your OP or internal authentication team.

For example, this is a section of an example discovery document provided by Google:

Overview of Steps in Looker

To update your license to include the OpenID Connect authentication feature, contact your Account Manager or open a support request in Looker’s Help Center by clicking Contact Us.

Once your license is updated, navigate to OpenID Connect in the left panel of the Admin section of Looker, then click the Enabled button to see the configuration options. They are organized into these sections:

While specifying this configuration, do not save your configuration until you have tested that Looker can talk to the OP and successfully retrieve user information. You can run the test multiple times before saving, which helps you see which parameters need configuration.

Any changes to configuration values do not take effect until you save them by clicking the Update Settings button at the bottom of the page.

Configuring OpenID Connect Auth Settings

Use the configuration information you obtained from your OP’s discovery document, your OP, or internal authentication team to enter connection settings in the following fields:

Identifier: The client identifier unique to your Looker instance. This should be provided by your OP.

Secret: The client secret key unique to your Looker instance. This should be provided by your OP.

Issuer: The secure URL that identifies your OP.

Audience: An identifier indicating to your OP who the client is. This is often the same as your Identifier value, but may be a different value.

Authorization URL: The URL of the OP where the authentication sequence begins. Often called authorization_endpoint in a discovery document.

Token URL: The URL where Looker retrieves an OAuth token after Looker has been authorized. Often called token_endpoint in a discovery document.

User Info URL: The URL where Looker will retrieve detailed user information. Often called userinfo_endpoint in a discovery document.

Scopes: A comma-separated list of scopes used by the OP to provide user information to Looker. You must include the openid scope and any scopes that include the information Looker requires, which includes email addresses, user names, and any user attributes configured on your Looker instance.

Configuring User Attributes Settings

In this section, you will map your OP’s claims to Looker user attributes.

In the User Attributes Settings section, enter the name of your OP’s claim that contains the corresponding information for each field. This tells Looker how to map those claims to Looker user information at login time. Looker isn’t particular about how claims are constructed, it’s just important that the claim information entered here matches the way that the claims are defined in your OP.

Standard Claims

Looker requires user name and email information for user authentication. Enter your OP’s corresponding claim information in this section:

Email Claim: The claim your OP uses for user email addresses, such as email.

First Name Claim: The claim your OP uses for user first names, such as given_name.

Last Name Claim: The claim your OP uses for user last names, such as family_name.

Note that some OPs use a single claim for names, rather than separating first and last names. If this is the case with your OP, enter the claim that stores names in both of the First Name Claim and Last Name Claim fields. For each user, Looker will use the contents up to the first space as the First Name and everything afterwards as the Last Name.

Attribute Pairings

Optionally, you can use the data in your OpenID Connect claims to automatically populate values in Looker user attributes when a user logs in. For example, if you have configured OpenID Connect to make user-specific connections to your database, you could pair your OpenID Connect claims with Looker user attributes to make your database connections user-specific in Looker.

To pair claims with corresponding Looker user attributes:

  1. Enter the claim as identified by your OP in the Claim field and the Looker user attribute you want to pair it with in the Looker User Attributes field.
  2. Check Required if you want to block login by any user account that is missing a value in that claim field.
  3. Click + and repeat these steps to add more claim and attribute pairs.

Note that some OPs can have “nested” claims as shown below:

In the example above, the locality claim is nested within the address claim. For nested claims, specify the parent and nested claims, separated by a slash ( / ) character. To configure Looker for the locality claim above, you would enter address/locality.

Configuring Role Settings

Optionally, you can assign Looker roles to users based on their OpenID Connect groups.

Assigning Roles in Looker Directly

If you choose not to use this option, you specify default roles and groups for new users in this section but otherwise assign Looker roles directly to users or assign roles to their Looker groups.

Leave the Set Roles from Groups switch off, and choose the default roles and groups that all new users will receive:

Assigning Roles Using OpenID Connect Groups

If you choose to use OpenID Connect groups to define roles, turn on Set Roles from Groups.

If this feature is on, all Looker roles will be overridden by the OpenID Connect roles.

Looker displays these settings:

Groups Claim: Enter the claim that your OP uses to store group names. Looker will make one Looker group for every OpenID Connect group that is introduced into the system by the Groups claim. Those Looker groups can be viewed on the Groups page of the Admin section of Looker. Groups can be used for setting content access controls and assigning user attributes.

Auth Requires Role: Turning this on means that users are required to have a role in order to log in to Looker. If it is off, that means your OpenID Connect users can authenticate to Looker even if they have no role assigned. Having no role set means that a user will not be able to see any data or take any action in Looker.

Configuring Migration Options

As explained in this section, Looker recommends that you enable Alternate Login and provide a merging strategy for existing users.

Alternate Login for Specified Users

Looker email/password logins are always disabled for regular users when OpenID Connect authentication is enabled. The Alternate Login for Specified Users option enables alternate email-based login using /login/email for admins and for specified users with the login_special_email permission.

Turning this on is useful as a fallback during OpenID Connect setup should OpenID Connect configuration problems occur later, or if you need to support some users who do not have accounts in your OpenID Connect directory.

Merge Users Using

Merge a first-time OpenID Connect login to an existing user account by one or more of the specified method here. Options are Looker Email/Password, Google, LDAP, and SAML.

If you have more than one system in place, you can specify more than one system to merge by in this field. Looker will look up users from the systems listed in the order that they are specified. For example, assume you created some users using Looker Email/Password, then you enabled LDAP, and now you want to use OpenID Connect. In the example above, Looker would merge by Email/Password first and then LDAP.

When a user logs in for the first time with OpenID Connect, this option will connect the user into their existing account by finding the account with a matching email address. If there is no existing account for the user, a new user account will be created.

Testing User Authentication

While [specifying this configuration], click Test OpenID Connect Authentication to test your OpenID Connect configuration.

Read the results of the test carefully, as some parts of the test can succeed even if others fail.

Tests will redirect out to the endpoints and will open a new browser tab. The tab displays:

You can use this test to verify the information received from the various endpoints is correct, and to troubleshoot any errors.


Saving Your Configuration

Be sure to first test your configuration and read the test results carefully to verify that all parts of the test succeeded. Saving incorrect OpenID Connect configuration information could lock yourself and others out of Looker.

Once you are done configuring settings and have verified that all parts of the test are succeeding, click Update Settings to save your configuration.