This page describes how to configure Looker to authenticate users via Lightweight Directory Access Protocol (LDAP). It includes instructions for linking LDAP groups to Looker roles and permissions.
A few things to keep in mind:
- Looker authentication uses LDAP’s “simple” authentication. “Anonymous” authentication is not supported.
- You must create a single LDAP user account that has read privileges to user entries and any group entries that will be used by Looker.
- Looker only reads from the LDAP directory (no writes).
- Looker can migrate existing accounts to LDAP via email address.
- Looker API usage does not interact with LDAP authentication.
Be Careful If Disabling LDAP Authentication
If you are logged into Looker using LDAP and want to disable LDAP authentication, be very careful to first:
- ensure that you have you have other credentials to log in and
- enable the Alternate Login option on the LDAP configuration page
Otherwise you could lock yourself and other users out of Looker.
LDAP Authentication needs to first be enabled by Looker. Please contact your Account Manager or email@example.com to enable this feature.
Once enabled, navigate to the LDAP Authentication page in the Admin section of Looker, then click on the Enabled button to see the following configuration options.
Set Up Your Connection
Looker supports transport/encryption via “LDAP in the clear” and “LDAP over TLS.” LDAP over TLS is strongly recommended. “StartTLS” and other encryption schemes are not supported.
- Enter your Host and Port information.
- Check the box next to TLS if you are using LDAP over TLS.
- If you are using LDAP over TLS, Looker enforces peer certificate verification by default. If you need to disable peer certificate verification, check No Verify.
- Click Test Connection. If any errors are surfaced, correct them before proceeding.
Looker requires access to an LDAP account that is password-protected. The LDAP account should have read-access to people entries, and to a new set of role entries. The Looker LDAP account does not require write access (nor access to any other aspects of the directory) and it does not matter what namespace the account is created in.
- Enter the Account DN and its password.
- Force No Paging: Check this box if your LDAP provider does not provide paged results. In some cases, this may help if you are not receiving any matches when searching for users, though it is not the only solution for such a problem.
- Test Authentication: If any errors are surfaced, ensure your authentication information is correct or contact your company’s LDAP administrator.
User Binding Settings
The details in this section specify how Looker will find users in your directory, bind for authentication, and extract user information.
- Set the Base DN, which is the base of the search tree for all users
- [Optional] Specify a User Object Class, which controls the types of results that Looker will find and return. This is useful if the Base DN is a mix of object types (i.e., people, groups, printers, etc), and you only want to return entries of one type.
- Set the Login Attrs, which defines the attribute(s) your users will use to log in. These must be unique per user, and something your users are familiar with as their ID within your system. For example, you might choose a user ID or full email address. If you add more than one attribute, Looker will search through both to find the appropriate user. Please be certain to select appropriate fields here; using something like first name and last name will not work as soon as you have two Jennifer Smiths, etc.
- Specify the Email Attr, First Name Attr, and Last Name Attr. This information tells Looker how to map those fields and extract their information at login time.
- Set the ID Attr, which indicates a field that Looker itself should use as the unique ID for users. This will generally be one of the login fields.
- Optionally, enter an Optional Custom Filter, which lets you provide arbitrary LDAP filters that will be applied when searching for a user to bind during LDAP authentication. This is useful if you want to filter out sets of user records, such as disabled users, or users in a different organization.
This example ldiff user entry demonstrates how to set corresponding Looker Settings:
Ldiff User Entry
dn: cn=mward,ou=People,dc=example,dc=com objectClass: person objectClass: inetOrgPerson objectClass: organizationalPerson objectClass: top cn: mward userpassword: normal givenname: Marcus telephonenumber: +1 408 555 5688 sn: Ward mail: firstname.lastname@example.org ou: People
Corresponding Looker Settings
Pairing LDAP User Attributes with Looker User Attributes
You can optionally use the data in your LDAP user attributes to automatically populate values in Looker user attributes when a user logs in. For example, if you have configured LDAP to make user-specific connections to your database, you could pair your LDAP user attributes with Looker user attributes to make your database connections user-specific in Looker.
Note that the LDAP attribute must be a user attribute, not a group attribute.
To pair LDAP user attributes with corresponding Looker user attributes:
- Enter the name of the LDAP user attribute in the LDAP User Attribute field and the name of the Looker user attribute you want to pair it with in the Looker User Attributes field.
- Check Required if you want to require that the LDAP attribute has a value in order for a user to log in.
- Click + and repeat these steps to add more attribute pairs.
Test User Information
- Enter a test user’s credentials and click the Test User Authentication button. Looker will attempt a full LDAP authentication sequence and show the result. Upon success, Looker outputs the user information from the directory plus some trace information about the authentication process which can aid in resolving configuration problems.
- Verify that authentication succeeds and that all fields are mapped correctly. For example, confirm that the
first_namefield doesn’t contain a value that belongs to
Note: You can test any user in your system by entering only the User ID, and omitting the User Password, then clicking Test User Information. This will test the mapping, but will not test authentication.
You can choose to map your existing LDAP groups to specific Looker roles and permissions. This is best for companies that already segment their users into groups that should receive similar permission sets. The alternative is to give all users the same default role when they log in for the first time.
To Give All Users the Same Default Role When They Log In
- Do not select the Set Roles from Groups option.
- Select default roles for new users from the drop-down.
- Select default groups for new users from the drop-down.
To Assign Roles Based on Groups
Looker will automatically create a Looker group for each LDAP group that you specify. You can then use these Looker groups for Space access control and assigning user attributes. However, you must still use the instructions below if you want to associate an LDAP group with a particular Looker role, instead of using Looker’s normal group interface. When authenticating users with LDAP, Looker only uses the roles and their permissions assigned through each user’s membership in an LDAP group. Even if you specify assigning a user to additional Looker groups, those additional roles and permissions are ignored — the only roles and permissions assigned to that user are those that come from their LDAP groups. This ensures that your LDAP groups continue to be your single source of truth.
- Select Set Roles from Groups to enable group mapping.
- Choose an option from the Group Finder Strategy drop-down to tell Looker how to find a user’s groups:
- Groups Have Member Attributes: This is the more common option. When looking for a group member, Looker will only return the groups to which a user is directly assigned. For example, if a user is a member of the “Database-Admin” group, and the “Database-Admin” group is a member of the “Engineering” group, a user would only get the permissions affiliated with the “Database-Admin” group.
- Groups Have Member Attributes (deep search): This option allows for groups to be members of other groups, which is sometimes referred to as LDAP nested groups. This means that a user can have the permissions of more than one group. For example, if a user is a member of the “Database-Admin” group, and the “Database-Admin” group is a member of the “Engineering” group, a user would get the permissions affiliated with both of these groups. Note that some LDAP servers (especially Microsoft ActiveDirectory) have support to automatically execute this type of deep search, even when the caller is doing what seems like a shallow search. That may be another method you can use to execute a deep search.
- Set a Base DN, which allows you to narrow the search, and can be the same as the Base DN specified in the User Binding Settings above.
- [Optional] Specify the Groups Object Class(es). As noted in the User Binding Settings, this allows the results that Looker returns to be constrained to a particular object type or set of types.
- Group Member Attribute is the attribute that, for each group, determines the things (in this case, probably the people) that are a member.
- Group User Attribute is the name of the LDAP user attribute whose value we will search for in the Group entries to determine whether a user is part of the group. This defaults to ‘dn’ (meaning that leaving it blank is the same as setting it to ‘dn’), which will result in LDAP using the full Distinguished Name to search Group entries.
- Repeat the steps listed in the Test User Information above to confirm that all role mappings were applied correctly.
- Decide whether Auth Requires Role, which means that a user has to have a role set for them to log in to Looker. If no role has been set for that user (via their group or otherwise), they will not be able to log in. If this box is not checked and the user has no role, they will be able to log in to Looker, but will have no permissions to access any data or perform any actions.
- Set the Group to Role Pairing
- Group DN: This should include the full Distinguished Name (case sensitive), which is the exact string that would exist in the LDAP search itself.
- Role: This drop-down will be populated with all the roles you have already created on your instance. You can choose more than one Looker role for each of your groups (roles are additive). To learn more about creating additional Roles on your instance, see the Roles documentation.
- Click + to add additional Group-Role mappings.
- Repeat the steps listed in the Test User Information above to confirm that all role mappings result in the expected list of roles for the user. Try this on various users, in various groups, to ensure that all of the mappings work as expected.
Migration and Integration Options
Note: Looker recommends is that both of these are enabled
Alternate Login for Admins and Specified Users
- Allow an alternate email-based login for Admins, and for users with the
login_special_emailpermission (read more about setting this permission in the Roles documentation). This option will appear on the Looker login page if you’ve turned it on and the user has the appropriate permission.
- This option is useful as a fallback during LDAP setup, if LDAP config problems occur later, or if you need to support some users who are not in your LDAP directory.
- Looker email/password logins are always disabled for regular users when LDAP is enabled.
Merge by Email
- This option allows Looker to merge first-time LDAP users with their existing Looker accounts, based on email address.
- If Looker cannot find a matching email address a new account will be created for the user.
Confirm the Settings
Be sure to thoroughly test your settings before confirming them. It’s also a good idea to enable the Alternate Login option until you have confirmed that these settings work as intended. Otherwise, you could lock yourself and other users out of Looker.
Click the Update button at the bottom of the LDAP configuration panel to save the settings and apply them immediately.
LDAP authentication can be disabled or re-enabled by changing the Disabled/Enabled radio buttons and clicking Update at any time.