Superset LDAP and Active Directory login setup

How Superset LDAP and Active Directory login works

Apache Superset supports LDAP authentication through Flask-AppBuilder, and the directory lookup can also return group membership that drives Superset role mapping. For a team that wants people to sign in with their directory accounts instead of local Superset passwords, the flow has three parts. Superset sends the username and password to the directory, and the directory decides whether the credentials are valid. If they are, Superset creates or updates a local user record for that account, so ownership of dashboards, charts and saved queries stays inside Superset's metadata database. The role mapping then decides which Superset roles that local user holds after each login.

Before planning the rollout, confirm the transport and the directory layout. Flask-AppBuilder supports STARTTLS with an ldap:// server and AUTH_LDAP_USE_TLS = True, and LDAP over TLS with an ldaps:// server and AUTH_LDAP_USE_TLS = False. Choose one and test it against your domain controllers or LDAP servers, including the certificate chain Superset's host trusts. Then confirm the search base, the user search filter and the attribute that holds the login name in your directory, because a wrong filter is the most common reason logins fail for only part of a population. Ask your directory team which service account Superset will bind with and what it is permitted to read.

This method covers password checks against an LDAP directory and does not cover Windows-integrated or Kerberos sign-in, which the supplied documentation does not describe for Superset. Users who expect a seamless desktop sign-in should be told that they will still type a password into Superset unless you add a separate SSO integration. Review the Flask-AppBuilder security documentation for the exact setting names in the release you deploy, and confirm any behavior you intend to rely on, such as how new users are created, in a staging environment first.

What you need before you configure LDAP login

LDAP login touches the Superset release, its metadata database, the Python image, the directory and the network between them. Confirm each item below before you edit the Superset configuration, because a gap in any one of them usually shows up as a failed login with little explanation.

Supported Superset release and metadata database

Start from a Superset release you can keep current, running on a metadata database inside the supported range: PostgreSQL 10 to 17 or MySQL 5.7 and 8.x. The SQLite default used by Quickstart and PyPI installs is not recommended for production, so an LDAP test on SQLite tells you little about the real deployment. Confirm the release and database versions against the Superset configuration documentation and your own environment before you start.

python-ldap in the Superset image

LDAP authentication in Flask-AppBuilder depends on the python-ldap package being installed in the same Python environment that runs Superset. Add it to the image you build, not to a running container, so every web and worker pod gets the same module. Check that the package builds against your base image's system libraries, since a missing library is a common cause of an import error at startup.

Service bind account with read rights

Create a dedicated service account that Superset uses to search the directory before it binds as the user. Give it read access to the user and group search bases only, with a strong password held in your secrets store. Do not reuse a personal administrator account, and record who owns the password so rotation does not break logins.

Directory layout and attribute names

Collect the base DN, the user and group search bases, the search filters and the exact attribute names for username, email and group membership. Active Directory uses names such as sAMAccountName for usernames and memberOf for group membership, but your forest may differ. Verify these values with a directory query from a host you control, and confirm the schema against the Flask-AppBuilder security documentation.

Trusted CA certificate for LDAPS or STARTTLS

Decide between LDAP over TLS with an ldaps:// server or STARTTLS on an ldap:// server, then obtain the certificate chain of the domain controller's issuing CA. Superset must trust that chain, or the TLS handshake fails. Plan how the CA file reaches every container, and confirm which option your domain controllers accept before you commit to one.

Network paths to the domain controllers

Confirm that every Superset web and worker node can reach the domain controllers on the chosen LDAP port, usually 389 for plain or STARTTLS and 636 for LDAPS, and that the firewall allows the return traffic. Ask the directory team which controllers are local to your site and whether they are read-only. Test from inside the cluster or container network, because a path that works from a workstation may not work from a pod.

Configure Superset to bind to your directory

This sequence takes Superset from a clean install to a working LDAP or Active Directory login, with TLS in place, a verified test bind, and group-based role mapping confirmed on a fresh login. Each step ends with a check so the platform team can confirm progress before moving on.

Install python-ldap in the Superset environment
The platform engineer installs the python-ldap package into the same Python environment that runs Superset, including any container image build used for web and worker processes. Install it in every environment that loads superset_config.py, since a web server without the library will fail when it tries to use LDAP. Confirm the build system has the native LDAP client libraries it needs, and ask your Superset deployment team to confirm the exact package requirements for your Python version. The check is a clean import of the ldap module from the Superset interpreter, run in the same shell or container that starts the web server.
Set AUTH_TYPE to LDAP in superset_config.py
Open superset_config.py, the configuration file that Superset loads at startup, and set AUTH_TYPE to the LDAP authentication type using the Flask-AppBuilder constant. Keep this file under version control and restrict who can change it, because it will also hold the bind credentials and the secret key. Restart the web server after the change so the new authentication type is loaded. The check is that the login page now shows a username and password form instead of the local account form, and that the server log has no configuration errors at startup.
Choose the TLS mode and set the server URI
Decide between STARTTLS and LDAPS before you write any connection settings. For STARTTLS, set AUTH_LDAP_SERVER to an ldap:// address and set AUTH_LDAP_USE_TLS to True. For LDAP over TLS, set AUTH_LDAP_SERVER to an ldaps:// address and set AUTH_LDAP_USE_TLS to False. Confirm with your directory team which ports and certificate chain your domain controllers support, and make sure the certificate authority that signed them is trusted by the Superset host. The check is a successful TLS handshake from the Superset host to the domain controller, verified with a directory client tool before you rely on it inside Superset.
Configure the bind user, search base and user filter
Create a read-only service account in the directory for Superset to bind with, and set AUTH_LDAP_BIND_USER and AUTH_LDAP_BIND_PASSWORD to its distinguished name and password. Set AUTH_LDAP_SEARCH to the base distinguished name where user objects live, and set AUTH_LDAP_UID_FIELD to the attribute that holds the login name, such as sAMAccountName in Active Directory or uid in OpenLDAP. Keep the bind password out of plain text where your secret management allows it. The check is a successful search for a known test user from the service account, using a directory client with the same base and filter, returning exactly one entry.
Map user attribute names to Superset fields
Set AUTH_LDAP_FIRSTNAME_FIELD, AUTH_LDAP_LASTNAME_FIELD and AUTH_LDAP_EMAIL_FIELD to the directory attribute names that hold each value, such as givenName, sn and mail in Active Directory. Superset uses the email field to match and display users, so confirm that every account allowed to sign in has a populated mail attribute. Ask the directory team to list the attributes available on a sample account before you set these names. The check is a login with a known test account that creates or updates the Superset user record with the correct first name, last name and email address shown on the user list.
Test a login with a known account
Sign in to Superset as a known directory user with a non-admin account, then sign in with a second known account so you can confirm two separate user records are created. Use the same account from the earlier directory search and check that the password prompt accepts the directory password and rejects a wrong one. Keep a local admin account available during testing so you can recover if the configuration locks out administrators. The check is a successful login that lands on the Superset home page, with the user visible in the user list under the expected username and email.
Configure group search and AUTH_ROLES_MAPPING
Set AUTH_LDAP_GROUP_FIELD and AUTH_ROLES_SYNC_AT_LOGIN as your design requires, then add AUTH_ROLES_MAPPING to map directory group distinguished names to existing Superset role names such as Alpha or Gamma. Use the group search settings described in the Flask-AppBuilder security documentation to define where groups are found, and confirm the exact key names against the version of Flask-AppBuilder your Superset release ships. Make sure every mapped group name matches the directory exactly, including case and full distinguished name. The check is a configuration that loads without error and a group list from the directory that matches the keys in the mapping dictionary.
Verify roles after a fresh login
Remove or change one test user's group membership in the directory, then have that user sign out and sign in again so Superset applies the mapping at login. Open the user record in the Superset user list and confirm that the roles shown match the groups the user now belongs to, and that roles tied to removed groups are gone. Repeat with a user in two mapped groups to confirm that roles combine as expected. The check is a user record whose roles match the directory groups after a fresh login, recorded in your test notes before any production user is onboarded.

Choosing LDAPS or STARTTLS for directory traffic

Flask-AppBuilder, which Superset is built on, supports two ways to protect LDAP traffic, and the choice is made in configuration. With LDAPS, the server URL uses ldaps:// and AUTH_LDAP_USE_TLS is set to False, so the connection is wrapped in TLS from the first packet. With STARTTLS, the URL uses ldap://, the connection starts in plain text, and AUTH_LDAP_USE_TLS is set to True so the client upgrades the session before any credentials are sent. Both protect the bind and search traffic, but LDAPS leaves no plain-text window to misconfigure, which is why many security teams prefer it. Confirm with your directory team which mode your domain controllers accept, because some environments only enable one of them and a mismatch shows up as a login failure rather than a clear error.

Whichever mode you choose, the Superset container must trust the certificate chain of the domain controller or LDAP server. The certificate must be issued by a CA that the container's trust store recognizes, which usually means adding your internal root and any intermediate certificates to the image or mounting them into the container used by the web and worker processes. Hostname matching matters too: the name in the ldaps:// URL or the STARTTLS URL has to match a subject or subject alternative name on the certificate. Using a raw IP address or a load balancer name that the certificate does not cover is a common cause of failures that look like authentication problems. Test the chain from inside the container, not from your workstation, since the container's trust store is the one that counts.

The bind account's password must never cross an unencrypted channel. Flask-AppBuilder sends the service account credentials during the bind before any user logs in, so a plain ldap:// connection without STARTTLS exposes that account to anyone on the path. Treat this as a hard requirement: use a read-only service account with the narrowest search rights, store its password as a secret outside the configuration file, and reject any configuration that points the bind at an unencrypted endpoint. Ask your security team to confirm that domain controllers refuse simple binds on unencrypted connections, since that setting determines whether a misconfigured Superset can still fail safely.

Mapping directory attributes and groups to Superset roles

This table compares each directory attribute and group with the Superset field or setting it feeds during LDAP login. Use it to list the attribute names your directory uses, then confirm each value in a staging instance before you open access to users.

Directory item	Superset field or setting	What to confirm in your environment
Username	AUTH_LDAP_UID_FIELD, the login name stored on the Superset user	uid in OpenLDAP or sAMAccountName in Active Directory are common. Confirm the attribute is unique and populated for every account.
Email	AUTH_LDAP_EMAIL_FIELD, the email address on the Superset user	Confirm the mail attribute is set for all users who need access, since missing values can leave the account incomplete.
Display name	AUTH_LDAP_FIRSTNAME_FIELD and AUTH_LDAP_LASTNAME_FIELD	Confirm givenName and sn are populated. These names appear in user lists and audit views.
Group membership	memberOf or a group search, read at login to find the user's groups	Confirm whether your directory returns nested group membership in memberOf. Nested groups may need a separate search.
Group to role mapping	AUTH_ROLES_MAPPING, with the group DN as key and a list of Superset role names as value	Confirm exact DN strings and capitalization, and that each Superset role exists before the first login.
Default role for new users	AUTH_USER_REGISTRATION_ROLE, applied when AUTH_USER_REGISTRATION is enabled	Use the least-privileged role your model allows, for example Gamma in an illustrative setup. Confirm the role name in your instance.
User in no mapped group	Governed by AUTH_USER_REGISTRATION and the default role setting	Test with a dummy account. Confirm whether the user gets the default role or is denied login in your version.
Group changes after login	AUTH_ROLES_SYNC_AT_LOGIN, which resyncs roles from groups at each login	Confirm whether a removed group takes effect only at the next login and how existing sessions are handled.

Hardening the LDAP login path

LDAP login moves trust from Superset to your directory, so the directory, the bind account and the Superset configuration all become part of the security boundary. The cards below cover the controls that keep that path narrow, encrypted, recoverable and observable.

Least-privilege bind account

Superset uses a service account to bind to the directory and search for users before it checks a password. Give that account read access only to the attributes and containers the login needs, and no rights to write, reset passwords or modify group membership. Ask the directory team to document who owns the account and when its password rotates, because a leaked bind password exposes every user record it can read.

LDAPS or STARTTLS with validation

Credentials should never cross the network in clear text. Flask-AppBuilder supports an ldap:// server with AUTH_LDAP_USE_TLS = True for STARTTLS, or an ldaps:// server with AUTH_LDAP_USE_TLS = False for LDAP over TLS. Confirm that the certificate chain is trusted by the Superset host and that validation is not disabled to make a test connection work, since a skipped check lets a spoofed directory capture passwords.

Search bases limited to needed OUs

A broad search base lets Superset authenticate and map roles for accounts it was never meant to serve, such as service or contractor objects. Set the user and group search bases to the organizational units that hold the people who should sign in, and test with an account outside that scope to confirm it is refused. Review the filter whenever the directory structure changes.

Break-glass local admin

If the directory, the certificate or the group mapping fails, administrators need a way back in. Keep one local Superset admin account that is excluded from directory-driven role sync, store its credentials in a sealed process owned outside the Superset team, and test that it signs in before go-live and after each configuration change. Record every use of it.

SECRET_KEY set and rotated

Superset requires a user-specified SECRET_KEY to start, a requirement added in version 2.1.0. Keep it out of the source tree, load it from your secret store, and when you rotate it, set PREVIOUS_SECRET_KEY so existing sessions and encrypted values keep working during the change. Confirm the rotation steps in the configuration documentation for your Superset version before you run them.

Removal ends access

Disabling a directory account should stop its Superset logins, but LDAP authentication does not remove a local user record on its own, so existing Superset roles and ownership can outlive the person. Confirm with a test account that a disabled or deleted directory user cannot sign in, and set a process to review or deactivate local accounts whose directory entries are gone.

Logging login failures

Failed binds, refused users and repeated password errors are the earliest signs of a credential attack or a broken directory connection. Decide where Superset and reverse proxy logs go, who reviews them, and what counts as an alert, such as bursts of failures against one account. Confirm which authentication events your Superset version writes to its logs before you rely on them for audit evidence.

Why LDAP login fails and how to fix it

This table pairs each common Superset LDAP or Active Directory login failure with its likely cause and a fix. Work through it in order when logins fail, because TLS and bind problems block everything that comes after them. Most failures trace back to the TLS setting, the bind account or the search filters rather than to Superset itself.

Symptom	Likely cause	Fix
Certificate verification error on LDAPS or STARTTLS	Superset cannot validate the directory server certificate, often because the issuing certificate authority is not trusted by the Superset host or container	Install the internal CA certificate in the Superset image or host trust store, then confirm the certificate name matches the server address used in AUTH_LDAP_SERVER
Handshake fails after enabling TLS	The TLS flag does not match the URL scheme: an ldap:// server with TLS off, or an ldaps:// server with STARTTLS switched on	Use ldap:// with AUTH_LDAP_USE_TLS = True for STARTTLS, or ldaps:// with AUTH_LDAP_USE_TLS = False for LDAP over TLS, and test each pairing
Bind fails for the service account	The bind DN is written as a bare username, the wrong domain format is used, or the account is locked or its password has expired	Use the full distinguished name for the bind account, confirm the password in the Superset configuration, and check the account status in the directory
User search finds nothing	AUTH_LDAP_SEARCH base is too narrow, or the filter uses the wrong attribute for the login name such as a UPN where sAMAccountName is expected	Widen the search base to the parent container, match the filter to the attribute users type at login, and test the search with an LDAP client before editing Superset
Group search returns no groups	The group search base or filter is wrong, group membership is stored on a different object class, or nested group membership is not resolved	Check the group base and filter against the directory schema, confirm the user object carries the expected membership attribute, and map only the groups the search actually returns
Users log in but get the wrong or no roles	AUTH_ROLES_MAPPING keys do not match the exact group names returned by the directory, including case and full DN form	Copy group names from the directory output, not from memory, and compare them one by one with the mapping keys in the configuration
Roles do not change until the user logs in again	Superset assigns roles when the login is processed, so changes made in the directory apply at the next sign-in	Ask users to sign out and back in after group changes, and document this behavior in the access process so administrators do not expect immediate updates
Users locked out after a directory change	A renamed account, moved object, disabled account or changed login attribute no longer matches the user record in Superset	Confirm the login attribute and search base still resolve the user, keep a local break-glass admin account outside the directory, and review account changes with the directory team

LDAP login or SSO: how the user experience compares

With LDAP, users see Superset's own login form. They type their directory username and password into that form, and Superset checks the password against the directory on their behalf. The screen looks familiar, but Superset is the place where the credential is entered, so the password passes through Superset's login flow. With SSO, Superset redirects the browser to the identity provider. Users sign in there, and that page can enforce multi-factor authentication, device checks and session lifetimes before Superset ever sees the user. Most people experience SSO as one sign-in shared across several internal tools.

Login screen: LDAP shows Superset's form, while SSO shows the identity provider's page.
Multi-factor authentication: With LDAP, any second factor must be built into the Superset flow, which is often not the case. With SSO, it is usually configured once at the identity provider.
Shared sessions: SSO can reuse an existing identity provider session, so users are not prompted again for other tools.
Password changes: Users change their password in the directory in both models, but SSO sessions may continue until they expire or are revoked.
Browser behavior: Confirm how sessions, logout and timeouts behave with your browsers and your identity provider before rollout.

Ask your identity owner which sign-in experience your staff already use for other internal applications.

Questions buyers ask before setting up Superset LDAP login

Can our internal team set up Superset LDAP login without a partner?

Yes, a team that already runs Superset and has directory administration skills can configure LDAP login in-house, because the work is configuration in superset_config.py plus testing. The harder part is coordination: someone must own the bind account, the certificate chain, the search base and the group mapping, and that person needs read access to the directory and a staging Superset to test against. Teams without a Flask-AppBuilder or Python background often find the TLS and mapping steps slow. A fixed-scope engagement, agreed in writing, can cover the same configuration, testing and handover if your team prefers not to carry it.

What makes LDAP login take more or less effort?

Four factors drive most of the effort:

Directory layout: a single domain with one search base is simpler than several domains, forests or nested organizational units that must all authenticate.
Group count: mapping a handful of groups to Superset roles is quick, while hundreds of groups or deeply nested membership need a tested filter and a naming convention.
TLS trust: getting LDAPS or STARTTLS to validate against your internal certificate authority is often the longest step.
Mapping rules: deciding which group grants which role, and what happens to users in no group, requires agreement from the owners of both sides.

Ask for each of these to be documented in the scope before work starts.

How long does Superset LDAP login take to set up?

The duration depends on your environment more than on Superset itself. A single domain with a working certificate chain and a short list of groups is the simplest case, while multiple domains, unclear group ownership or a certificate issued by an internal authority that the Superset host does not trust will extend the schedule. Timelines should come from the written scope, which lists the environments, the number of directories and the groups to map. Ask for the duration to be split into discovery, staging tests and the production change window, since directory approvals often take longer than the configuration.

What does the work need from the directory and security teams?

The directory team usually provides a read-only bind account, the search base and user and group attributes, and confirmation of which groups are intended for Superset. The security team should review whether the connection uses LDAPS or STARTTLS, which certificate authority signs the directory certificate, and where the bind credentials are stored. Both teams should approve the group-to-role mapping before it goes live, and they should agree who removes access when someone leaves. Plan these reviews early, because they gate the staging tests.

Is SSO a better choice than LDAP login for Superset?

It depends on what your organization already runs. Flask-AppBuilder supports LDAP directly, and it also supports OAuth2 providers, so SSO through an identity provider is often preferred when that provider already fronts your applications, supports multi-factor policy and centralizes deprovisioning. Direct LDAP login keeps the directory as the source of truth without an extra service, but each Superset instance talks to the directory itself and usually needs its own bind credentials. Compare both options against your identity architecture before choosing, and see the sibling pages on SSO providers for the trade-offs.

Do Windows Server licenses or lifecycle dates matter for our Active Directory domain controllers?

They matter if you plan to host new domain controllers, because licensing and support windows shape the cost and the upgrade plan. According to Microsoft's Windows Server 2025 pricing page, Standard and Datacenter are licensed per core with a minimum of 16 cores per server and 8 per processor, and each user or device accessing the server needs a Windows Server Client Access License. The same page lists suggested prices of 1,176 US dollars for Standard and 6,771 US dollars for Datacenter for 16 core licenses, and says prices vary by region. Microsoft's lifecycle page says Windows Server 2025 has mainstream support ending November 14, 2029 and extended support ending November 15, 2034, and that Windows Server 2022 extended support ends October 15, 2031. Confirm current terms with your Microsoft reseller, since your agreement and region may differ.

What should we ask for in a written scope for LDAP login?

Ask for the directory and Superset versions in scope, the connection type (LDAPS or STARTTLS), the certificate trust process, the bind account handling, the group-to-role mapping table, and the test cases for valid users, users in no group and disabled accounts. Ask which environments are covered, how production change is handled and what documentation and handover you receive. Also ask how the scope treats future changes to groups, because mapping drift is the most common source of access problems after go-live.

How DeployOpen scopes and delivers Superset directory login

DeployOpen plans and implements Apache Superset directory login inside your own infrastructure, from the LDAP or Active Directory connection through group-to-role mapping and handover. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

Confirm which directory, domain controllers or LDAP servers Superset must reach, and where they sit relative to the network.
Agree whether the connection uses LDAPS or STARTTLS and who owns the certificate chain.
Define which directory groups map to which Superset roles, and which break-glass local admin remains.

How we build

Configure the Flask-AppBuilder LDAP settings in the Superset configuration, with search filters tested against a staging directory first.
Set up group search and AUTH_ROLES_MAPPING so role assignment follows directory membership at each login.
Test failed binds, locked or disabled accounts, users in many groups and the first-login experience before any production cutover.

How we hand over

Deliver the configuration, mapping table, certificate and service account notes, and a written test record.
Document how to add a directory group, change a role mapping and rotate the bind credentials safely.
Walk your administrators through troubleshooting login failures and the upgrade checks that touch authentication settings.

How we support

Offer ongoing support, upgrades and testing as a retainer after handover, scoped to your Superset version.
Re-verify the directory connection and role mapping during each planned Superset upgrade, following your staging process.
Agree in writing who handles directory changes, certificate renewals and access reviews after the project closes.

Apache Superset LDAP and Active Directory login