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:
- Only disable LDAP authentication (while you are logged into Looker via LDAP) if you have other credentials to login, and you've enabled the Alternate Login option on the LDAP configuration page. You could lock yourself out of the app if you do not follow these steps.
- 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.
LDAP Authentication needs to first be enabled by Looker. Please contact your Account Manager or firstname.lastname@example.org 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 button next to TLS if you are using LDAP over TLS.
- Click Test Connection - if any errors are surfaced, correct them before proceeding.
The LDAP server requires you to create a new, password-protected user entry for Looker. It 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 user 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 login. 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 Smith's, 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.
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: email@example.com ou: People
Corresponding Looker Settings
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.
Looker will automatically create a Looker group for each LDAP group that you have. You can then use these Looker groups for Space access control. 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. This ensures that your LDAP groups continue to be your single source of truth.
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 dropdown.
- Select default groups for new users from the dropdown.
To Assign Roles Based on Groups
- 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 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 attribute from the User entry whose value we will search for in the Group entries. This defaults to 'dn' (meaning that leaving it blank is the same as setting it to 'dn').
- 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 into 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 into 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.