---
title: "LDAP"
description: "Authenticate people against your LDAP directory and map LDAP groups to Metabase groups."
url: "https://www.metabase.com/docs/latest/people-and-groups/ldap"
version: "65"
---

> For the complete documentation index, see [llms.txt](https://www.metabase.com/docs/llms.txt).

# LDAP

Metabase supports authentication with Lightweight Directory Access Protocol (LDAP).

## Required LDAP attributes

You need to set up your LDAP directory with these attributes:

- email (defaulting to the `mail` attribute)
- first name (defaulting to the `givenname` attribute)
- last name (defaulting to the `sn` attribute).

If your LDAP setup uses other attributes for these, you can change them in the **Attributes** section of the LDAP settings page. The section becomes available after you save your server settings.

![Attributes](https://www.metabase.com/docs/latest/people-and-groups/images/ldap-attributes.png)

Your LDAP directory must have the email field populated for each entry that will become a Metabase user, otherwise Metabase won't be able to create the account, nor will that person be able to log in. If either name field is missing, Metabase will use a default of "Unknown," and the person can change their name in their [account settings](https://www.metabase.com/docs/latest/people-and-groups/account-settings.md).

On self-hosted Metabases, you can also set these attribute names with the environment variables [`MB_LDAP_ATTRIBUTE_EMAIL`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_attribute_email), [`MB_LDAP_ATTRIBUTE_FIRSTNAME`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_attribute_firstname), and [`MB_LDAP_ATTRIBUTE_LASTNAME`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_attribute_lastname), or, on Pro and Enterprise plans, in the [config file](https://www.metabase.com/docs/latest/configuring-metabase/config-file.md).

## Enabling LDAP authentication

To enable LDAP authentication, go to **Admin** > **Settings** > **Authentication** > **LDAP** and click **Set up**. Fill out the form, then click **Save and enable**.

Until you save your server settings, the **Attributes** and **Group mapping** sections stay locked. You can edit **User provisioning** before you save.

## Server settings

- **LDAP host** (required): Your server hostname. For example, `ldap.yourdomain.org`.
- **LDAP port**: The server port, usually 389, or 636 if you use SSL.
- **LDAP security**: None, SSL, or StartTLS.
- **Username or DN**: The distinguished name to bind as, if any. Metabase uses this name to look up information about other users.
- **Password**: The password to bind with for the lookup user.

Then save your changes. Metabase will automatically pull the [required attributes](#required-ldap-attributes) from your LDAP directory.

On self-hosted Metabases, you can also set these server settings with the environment variables [`MB_LDAP_HOST`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_host), [`MB_LDAP_PORT`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_port), [`MB_LDAP_SECURITY`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_security), [`MB_LDAP_BIND_DN`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_bind_dn), and [`MB_LDAP_PASSWORD`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_password).

## User provisioning

User provisioning is enabled by default. When someone logs in via LDAP, Metabase creates an account for them if they don't have one, and reactivates their account if it is deactivated. The switch saves on its own, so you don't need to click **Save changes** after you change it.

If you disable user provisioning, users without accounts or with deactivated accounts will not be able to log in.

On self-hosted Pro and Enterprise plans, you can also turn user provisioning on or off with the [`MB_LDAP_USER_PROVISIONING_ENABLED`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_user_provisioning_enabled) environment variable or in the [config file](https://www.metabase.com/docs/latest/configuring-metabase/config-file.md).

## User schema

The **User schema** section on this same page is where you can adjust settings related to where and how Metabase connects to your LDAP server to authenticate users.

### User search base

**User search base** is required. Enter the _distinguished name_ (DN) of the entry in your LDAP server that Metabase should use as the starting point when searching for users.

For example, let's say you're configuring LDAP for your company, WidgetCo, where your base DN is `dc=widgetco,dc=com`. If entries for employees are all stored within an organizational unit in your LDAP server named `People`, you'll want to supply the user search base field with the DN `ou=People,dc=widgetco,dc=com`. This tells Metabase to begin searching for matching entries at that location within the LDAP server.

On self-hosted Metabases, you can also set the user search base with the [`MB_LDAP_USER_BASE`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_user_base) environment variable or, on Pro and Enterprise plans, in the [config file](https://www.metabase.com/docs/latest/configuring-metabase/config-file.md).

### User filter

You'll see the following grayed-out default value in the **User filter** field:

```
(&(objectClass=inetOrgPerson)(|(uid={login})(mail={login})))
```

When a person logs into Metabase, this command confirms that the login they supplied matches either a UID _or_ email field in your LDAP server, _and_ that the matching entry has an objectClass of `inetOrgPerson`.

This default command will work for most LDAP servers, since `inetOrgPerson` is a widely-adopted objectClass. But if your company for example uses a different objectClass to categorize employees, this field is where you can set a different command for how Metabase finds and authenticates an LDAP entry upon a person logging in.

On self-hosted Metabases, you can also set the user filter with the [`MB_LDAP_USER_FILTER`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_user_filter) environment variable or, on Pro and Enterprise plans, in the [config file](https://www.metabase.com/docs/latest/configuring-metabase/config-file.md).

## Group mapping

Instead of manually assigning people to [groups](https://www.metabase.com/docs/latest/people-and-groups/managing.md#groups), use [group mappings](https://www.metabase.com/learn/metabase-basics/administration/permissions/ldap-auth-access-control#group-management) to assign them based on their LDAP groups.

To map an LDAP group to a Metabase group:

1. In the **Group mapping** section, turn on the toggle.
2. Next to **Manual group mappings**, click **New**.
3. Enter the distinguished name for the LDAP group, such as `cn=Accounting,ou=Groups,dc=example,dc=org`.
4. From **Pick Metabase group**, select the Metabase groups that people in this LDAP group should be added to.
5. Click **Add mapping**.
6. Repeat steps 2 to 5 for each group you want to map.

Metabase saves each mapping as soon as you add, edit, or remove it. To edit a mapping, hover over it and click the pencil icon.

Some LDAP directories list each person's groups on their own entry. If yours does, leave **Group search base** empty. Otherwise, enter the DN where your group entries live.

On self-hosted Metabases, you can also set the group mapping toggle, the mappings themselves, and the group search base with the environment variables [`MB_LDAP_GROUP_SYNC`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_group_sync), [`MB_LDAP_GROUP_MAPPINGS`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_group_mappings), and [`MB_LDAP_GROUP_BASE`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_group_base).

![Group Mapping](https://www.metabase.com/docs/latest/people-and-groups/images/ldap-group-mapping.png)

Some things to keep in mind regarding group mapping:

- Metabase syncs membership of the Administrators group like any other group.
- Updates to a person's group membership based on LDAP mappings are not instantaneous; the changes will take effect only _after_ people log back in.
- People are only ever added to or removed from mapped groups. The sync has no effect on Metabase groups that don't have an LDAP mapping.

### Remove a group mapping

To remove a mapping, hover over it and click the trash icon. Metabase asks what should happen to the Metabase group:

- **Nothing, just remove the mapping**
- **Also remove all members from this group**. Members keep their Metabase accounts.
- **Also delete the group**

Then click **Remove mapping**. Removing members or deleting a group takes effect immediately and can't be undone.

If the mapping points to a built-in group such as Administrators, Metabase doesn't offer these options. It removes the mapping without changing the group or its members.

**Also delete the group** isn't available when another mapping uses the same Metabase group.

### Group membership filter

> LDAP advanced features are only available on [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans (both self-hosted and on Metabase Cloud).

If your directory doesn't list each person's groups on their own entry, Metabase looks up membership on the group entries instead. **Group membership filter** sets that lookup filter. Metabase replaces the placeholders `{dn}` and `{uid}` with the person's distinguished name and UID.

On self-hosted Metabases, you can also set the filter with the [`MB_LDAP_GROUP_MEMBERSHIP_FILTER`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_group_membership_filter) environment variable or, on Pro and Enterprise plans, in the [config file](https://www.metabase.com/docs/latest/configuring-metabase/config-file.md).

## Syncing user attributes with LDAP

> LDAP advanced features are only available on [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans (both self-hosted and on Metabase Cloud).

Metabase always reads people's email, first name, and last name from your LDAP directory. If you turn on [group mapping](#group-mapping), Metabase also reads their groups. You can also sync other [user attributes][user-attributes-def], such as roles, from your LDAP directory.

To choose which user attributes to sync, list them, separated by commas, in the [`MB_LDAP_SYNC_USER_ATTRIBUTES_ALLOWLIST`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_sync_user_attributes_allowlist) environment variable or as `ldap-sync-user-attributes-allowlist` in the [config file](https://www.metabase.com/docs/latest/configuring-metabase/config-file.md). By default, the list is empty, so Metabase doesn't sync any user attributes. To turn off user attribute syncing entirely, set [`MB_LDAP_SYNC_USER_ATTRIBUTES`](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables.md#mb_ldap_sync_user_attributes) to `false`.

## Troubleshooting login issues

- [Can't log in](https://www.metabase.com/docs/latest/troubleshooting-guide/cant-log-in.md).
- [Troubleshooting LDAP](https://www.metabase.com/docs/latest/troubleshooting-guide/ldap.md)

## Further reading

- [Using LDAP for authentication and access control](https://www.metabase.com/learn/metabase-basics/administration/permissions/ldap-auth-access-control).
- [Permissions overview](https://www.metabase.com/docs/latest/permissions/start.md).

[google-saml-docs]: https://www.metabase.com/docs/latest/people-and-groups/saml-google.md
[jwt-docs]: https://www.metabase.com/docs/latest/people-and-groups/authenticating-with-jwt.md
[saml-docs]: https://www.metabase.com/docs/latest/people-and-groups/authenticating-with-saml.md
[user-attributes-def]: https://www.metabase.com/glossary/attribute#user-attributes-in-metabase
