How Superset signs users in with Microsoft Entra ID
Superset can sign users in through Microsoft Entra ID, so people use their work account and get Superset roles from their group membership instead of local accounts. Entra ID is the identity provider and Superset is the client application. Superset is built on Flask-AppBuilder, which supports OAuth2 providers, and the Azure provider is the one used for Entra ID. When a user signs in, Entra ID authenticates them and returns tokens to Superset. Group membership reaches Superset as claims in those tokens, and AUTH_ROLES_MAPPING translates those group values into Superset roles. Your design therefore depends on two things: the app registration that defines what Entra ID issues, and the mapping that decides what Superset grants.
Entra ID is not the same product as on-premises Active Directory. Active Directory Domain Services runs on Windows Server and uses LDAP, Kerberos and Windows-integrated authentication, while Entra ID is a cloud identity service that SaaS and web applications, including Superset, sign in against directly. Organizations with existing Active Directory usually sync identities to Entra ID with Microsoft Entra Connect, so Superset sees the users and groups that the sync has pushed to the tenant. Confirm for your tenant which users and groups are synced, which are cloud-only, and whether the group objects Superset will rely on are the ones your administrators actually maintain. A user who is absent from the tenant cannot sign in through this path, and a group that is not synced cannot grant a role.
Before you configure anything, confirm three points with your Entra ID administrators: which tenant and endpoints Superset will trust, whether group membership will arrive as object IDs or names in the token, and what happens when a user belongs to more groups than the token can carry. The last point is the group overage limit, which is covered in the next section. Also decide now how you will keep a local break-glass administrator that works when Entra ID is unavailable, because a misconfigured OAuth block can lock every user out of the application.
What you need before registering the app in Entra ID
Most delays in a Superset single sign-on project come from missing prerequisites, not from the Entra ID configuration itself. The items below cover the Superset platform, the database behind it, the tenant access you need, the group decisions and the test environment that all have to be settled before anyone registers an application.
A running Superset with a supported metadata database
Confirm that Superset is deployed with PostgreSQL or MySQL as its metadata database, not the SQLite default used by quickstart and PyPI installs. The configuration documentation lists supported ranges of PostgreSQL 10 to 17 and MySQL 5.7 and 8.x. Check your database version against that list, because the role mapping stored in the metadata database depends on it.
A user-specified secret key
Superset will not start without a SECRET_KEY that you set yourself, so the value must be generated and stored in your secrets manager before the OAuth settings are added. Record how you will rotate it, because PREVIOUS_SECRET_KEY is the supported path for rotation. Changing the key without this plan can invalidate existing sessions and encrypted values.
A stable public HTTPS callback URL
Entra ID will redirect users back to a fixed Superset callback address after sign-in, so the public hostname, DNS record and TLS certificate must be settled first. Avoid changing the hostname later, since every redirect URI in the app registration must match exactly. Confirm the hostname for production and staging separately so that test sign-ins do not use production redirect entries.
Tenant rights to register apps and manage groups
The person configuring the integration needs rights to register an application and to view or create the security groups used for role mapping. Confirm with your Microsoft Entra ID administrators who holds these roles. Also confirm that a tenant administrator will approve any delegated permissions the app requests, since user consent may be restricted in your tenant.
Group-to-role decisions
Decide which Entra ID groups map to which Superset roles before registration, and name them consistently. Mapping is driven by group identifiers in the token, so a group that is not created or not assigned to the app will grant no access. Agree who owns each group and how membership changes are approved, because these groups become your access model in Superset.
Staging Superset and upgrade checks
Confirm which Superset release you run, then read the upgrade guidance and the UPDATING.md breaking change notes for any version you are moving to before you change authentication. Build a staging Superset with the same release, database type and callback pattern, and test sign-in, role mapping and a break-glass admin there first. Back up the metadata database before any change to production.
Configuring the Entra ID app registration and Superset OAuth provider
This sequence registers Superset as an application in your Microsoft Entra ID tenant, passes group identifiers in the sign-in token, and wires the OAuth provider into Superset so that a test user can sign in and land with the expected role.
Register the Superset application in the tenant
An administrator with rights to register applications in the Entra ID tenant creates a new app registration for Superset, choosing a name that identifies the environment, such as staging or production. Record the application (client) ID and the directory (tenant) ID from the overview page, since both appear in the provider configuration later. Keep these identifiers in your configuration management system, not in a shared document. The step is complete when the registration appears in the tenant with both identifiers recorded and the owner is an accountable team, not a single person.
Create a client secret and note its expiry
Under the app's certificates and secrets settings, create a client secret for the Superset backend. Store the secret value in your secrets manager at creation time, because the portal does not show it again. Record the expiry date in your renewal calendar and assign an owner for rotation before it lapses, since an expired secret will break sign-in for every user. The step is complete when the secret is stored, the expiry date is written down with a named owner, and no copy of the secret remains in version control or tickets.
Set the redirect URI to the Superset callback
In the app's authentication settings, add a web redirect URI that points to the OAuth authorized callback path on your Superset host, using HTTPS and the exact hostname users will open. The path must match what your Superset release expects, so confirm it in the current configuration documentation for your version rather than copying it from an older example. Mismatched schemes, ports or trailing slashes are a common cause of failed logins. The step is complete when the URI in Entra ID matches the Superset public URL and callback path character for character.
Add group claims to the token configuration
In the token configuration section, add a groups claim so that Entra ID includes group identifiers in the ID or access token. Choose security groups by object ID and confirm the claim type your Superset provider code expects. If a user belongs to more groups than the token can carry, Entra ID does not send the full list, so plan for that case now by reviewing the group overage behavior in Microsoft's documentation and deciding whether to limit the groups assigned to the app. Test with a pilot user and decode the token to confirm the expected group identifiers appear. The step is complete when a test user's token lists the groups you plan to map.
Add the Azure OAuth provider block to Superset
In the Superset configuration file, add an OAuth provider entry for Azure using your tenant-specific authorization, token and metadata endpoints, along with the client ID and secret from earlier steps. Read secrets from environment variables or your secrets manager rather than hard-coding them. Verify every key name, provider setting and endpoint format against the Superset configuration documentation for your release, because these keys have changed over time and examples from memory can be wrong. Restart the web and worker processes after the change. The step is complete when Superset starts cleanly and the login page offers the Microsoft option.
Confirm the test user signs in and returns
Sign in with a pilot account that belongs to one of the mapped groups. Consent to the requested permissions if prompted, and confirm the browser returns to Superset and lands on the dashboard list without an error page. Check the Superset logs for the callback and any warnings about missing claims or unknown providers. If the login loops or fails, compare the redirect URI and the endpoint values first. The step is complete when the pilot user reaches an authenticated Superset session from a clean browser session.
Confirm the account and role assignment
Open the user list in Superset as an administrator and confirm that the pilot account was created with the role expected for its Entra ID group, based on your role mapping configuration. Repeat the test with one account from a group that should receive no elevated access, and confirm it gets only the default role you intended. Record the results in your change log. The step is complete when both test accounts show the expected roles and the results are documented before any wider rollout begins.
Mapping Entra ID groups and claims to Superset roles
This table traces each Entra ID attribute or claim to the Superset user field or role it populates, and names who should own each decision. Read it top to bottom as the path a sign-in takes, from identity token to Superset role assignment. The main takeaway is that group object IDs are opaque, so a written register linking each ID to a Superset role is what keeps access reviewable.
| Entra ID attribute or claim | Superset field or role it populates | Notes for the team | Decision owner |
|---|---|---|---|
| User principal name or email | Superset username or email field used for the account | Confirm which claim your OAuth configuration reads and that it is unique and stable in your tenant. | Identity team |
| Display name | Superset first and last name display | Used for display only. Do not rely on it for access decisions because names can change. | Identity team |
| Object ID of the user | Stable subject identifier for the account link | Object IDs do not change when a user is renamed, so they suit long-term account linking. Confirm the claim your provider returns. | Identity team |
| Group object IDs in the groups claim | Input to AUTH_ROLES_MAPPING, which maps each group to one or more Superset roles | Group IDs are opaque GUIDs. Keep a register that records which ID maps to which Superset role and who approved it. | Data owners with the identity team |
| Group overage indicator | No direct Superset field. Signals that group membership must be resolved another way | When a user belongs to many groups, Entra ID may not include them in the token. Confirm the overage behavior and your fallback before go-live. | Identity team |
| App roles assigned to the enterprise application | Optional input to AUTH_ROLES_MAPPING as an alternative to group IDs | Use only if the team chooses app roles. App roles are defined and assigned inside the application registration, so they need a named administrator. | Application owner |
| Superset role names | Target roles such as Admin, Alpha, Gamma or custom roles | Role names should follow a naming convention agreed with the data owners, for example one prefix per data domain and access level. | Data owners |
| Default role for new users | Role assigned when a first sign-in matches no mapping | Set the default to the least privileged role that still lets a user sign in. Confirm it grants no dataset access by accident. | Security team |
| Break-glass local admin account | Local Superset account that bypasses SSO for recovery | Keep it outside the mapping logic, store its credentials under dual control, and test the login path on a schedule. | Security team and platform owner |
What the group overage limit means for your users
When a user belongs to a small number of groups, Microsoft Entra ID places the group object identifiers directly in the groups claim of the token. Superset receives that claim during sign-in, and the AUTH_ROLES_MAPPING setting translates each group identifier into a Superset role. In this case, the token is the only source Superset needs, so role assignment happens at login without an extra call to Microsoft Graph.
- Token contents: The groups claim lists object IDs, not display names, so the mapping keys must be the GUIDs of the groups in your tenant.
- Login-time sync: Roles are reassigned each time the user signs in, so a removed group takes effect at the next login.
- Group scope: Only groups the token configuration includes appear in the claim, so confirm which group types you selected when you configured the claim.
- Predictable behavior: Troubleshooting stays simple because the claim you inspect in a decoded token is exactly what Superset maps.
- Maintenance: Each new group requires a mapping entry, so the number of groups should stay within what your team can review.
Before you rely on this path, decode a token for a typical user and confirm that every expected group identifier appears in the claim.
When a user belongs to more groups than the limit Microsoft allows in a token, Entra ID omits the full list and returns an overage indicator instead. The token then does not contain the memberships Superset needs, so a mapping that depends on the groups claim will silently grant the wrong role or no role. Users in many groups are often the administrators and power users whose access matters most, so this failure deserves attention before go-live.
- Restrict the claim: Limit the groups claim to groups assigned to the Superset enterprise application, which keeps the count low for most users.
- Use app roles: Assign Superset roles as Entra ID app roles and map those values, which avoids sending group lists at all.
- Read from Microsoft Graph: Have the application call Microsoft Graph for group membership, which requires a separate permission and an administrator consent decision.
- Reduce group sprawl: Audit nested and unused groups, since every extra membership counts against the token.
- Check the outcome: A user who falls back to a default role may appear to log in normally, so monitor role assignments after sign-in.
Confirm the current overage threshold and token behavior for each token type in Microsoft's documentation, then test with the user who belongs to the most groups in your tenant.
Each workaround trades administrative effort against the directory permissions and token design your security team will review. Restricting the claim is the lightest change but depends on keeping the assigned-group list short. App roles keep Superset authorization inside the application registration and are easy to audit per user. Microsoft Graph lookups give the most flexibility for large memberships but add an outbound call, a permission grant and error handling that your team must own.
- Assignment-based limits: Assigning users to the application keeps the groups claim focused on Superset-relevant groups.
- Role-based design: App roles let owners see Superset access in the Entra ID application, which suits smaller role sets.
- Graph permission review: Reading membership needs a permission that an administrator must approve, so document the business reason.
- Caching behavior: Any lookup that runs at login adds latency and a failure mode, so decide how Superset behaves when Graph is unreachable.
- Ongoing review: Each choice recurs as groups change, so assign an owner to review mappings after organizational changes.
Ask your identity team to write the chosen design down with its failure behavior before you build the mapping.
Testing proves which path your tenant takes, and it must use real membership data rather than a sample user with a few groups. Choose the account with the most group memberships, including nested groups that your mapping depends on, and sign in to Superset with that account. Compare the role Superset assigns with the role you intended, then repeat the check after any group change.
- Pick the heaviest user: Identify the account with the most memberships, because it exposes the overage case first.
- Decode the token: Inspect the claims for the overage indicator and confirm whether the group list is present.
- Compare outcomes: Record the Superset role after login and match it to the expected mapping.
- Test removal: Remove a group, sign in again, and confirm the role changes as expected.
- Document results: Keep the test record with the identity design so auditors and future owners can repeat the check.
Confirm the expected behavior with Microsoft's current token documentation for your token type, and rerun the test whenever you change the claim configuration.
Securing the Entra ID login and the Superset secret key
The Entra ID login and the Superset secret key both decide who can reach your dashboards and whether their sessions can be trusted. The controls below cover the app registration, the callback, the key lifecycle and the sign-in evidence you review before go-live. They do not replace the separate Superset hardening review of roles, data access and session settings.
Keep the client secret out of source control
The Entra ID client secret lets Superset prove its identity during the OAuth code exchange, so anyone holding it can impersonate the application. Store it in a secrets manager or an environment variable injected at deploy time, never in superset_config.py committed to a repository. Confirm that your build logs, container images and configuration backups do not contain it.
Track client secret expiry
Entra ID client secrets have a fixed expiry chosen when the secret is created. When it lapses, every Superset sign-in through Entra ID fails at once, often during business hours. Record the expiry date in your calendar or ticketing system with reminders well ahead of it, and plan the rotation as a change: create the new secret, update the stored value, restart Superset and then remove the old secret.
Restrict the app to assigned users
By default, a directory user in the tenant may be able to request a token for an enterprise application unless assignment is required. Turn on the option that requires user assignment, then assign the security groups that should reach Superset. Test with one account that is not assigned and confirm the sign-in is refused before you rely on the restriction.
Require HTTPS on the callback
The redirect URI registered for the app, the one Superset uses to receive the authorization code, should use the https scheme on the public hostname that users reach. Plain HTTP exposes the code and session cookies on the network path and is not a valid setup for production. Confirm the reverse proxy forwards the original scheme so Superset builds matching redirect URLs.
Plan SECRET_KEY rotation
Superset requires a user-specified SECRET_KEY to start, and it signs session data, so a weak or leaked key lets an attacker forge sessions. Superset supports rotation through PREVIOUS_SECRET_KEY, which lets existing sessions remain valid while the new key takes over. Write the rotation steps into your runbook, test them in staging first, and back up the metadata database before any change.
Review Entra ID sign-in logs in testing
The Entra ID sign-in logs show each attempt, the application, the user, the conditional access result and the error code when a login fails. Review them during testing with an assigned user, an unassigned user and a failed attempt, so you can match each Superset behavior to a log entry. Keep these records with your go-live evidence, since they show the restriction and the sign-in path worked as designed.
Keeping a break-glass admin that works without Entra ID
A break-glass admin is a separately controlled Superset administrator account that still works when the identity provider, a tenant conditional access policy or the group-to-role mapping locks out every administrator. Without one, a single bad change to the Entra ID app registration, a claim format change, or an AUTH_ROLES_MAPPING error can leave no one able to sign in to Superset to fix it. The team has to decide, before go-live, which account is kept, where its credentials are stored, who may use it, how each use is logged and alerted, and how the account is tested on a schedule in staging. Confirm with your own identity team whether the account lives in the Superset metadata database or is provisioned some other way, because that choice determines what still works during an outage.
The account must still work when Entra ID is unavailable. That means it cannot depend on a federated sign-in path, a conditional access rule that Entra ID evaluates, or a group claim being present in a token. Keep the password in a vault or sealed envelope controlled by people outside the daily Superset administration team, and restrict who can retrieve it. Every use should generate an alert to a channel the security team watches, and the reason for use should be recorded in your incident system. Also check that the metadata database and the Superset web tier used for emergency sign-in are reachable from the network paths your administrators use during an incident, since a break-glass account on an unreachable host is no help.
Rotate the password after every use, whether the use was a drill or a real incident. Rotation should be a documented step in the runbook, not something left to memory, and the new credential should be stored back in the controlled location before the incident is closed. Test the procedure on a schedule in staging: simulate an Entra ID sign-in failure, confirm the break-glass account signs in, confirm the alert fires, confirm a mapped role still exposes the admin screens needed to repair the mapping, and then rotate the credential. Record each test so auditors can see the control operating over time. Review the approach whenever you upgrade Superset, because login and role-handling behavior changes between releases and the Superset upgrade documentation asks you to test in staging first.
Why Entra ID sign-in to Superset fails
This table lists the failures most often seen when Superset sign-in through Microsoft Entra ID breaks, with the likely cause and the fix for each. Start with the Entra ID sign-in logs and the Superset application logs, because they show which step rejected the request before you change any setting.
| Symptom | Likely cause | Fix |
|---|---|---|
| AADSTS50011 or redirect error after Microsoft login | Redirect URI in the app registration does not exactly match the callback URL Superset sends | Compare the registered redirect URI with the Superset callback path and scheme character by character, then update the registration or the public base URL |
| Login fails before the Microsoft sign-in page appears | Tenant identifier or endpoint in the OAuth provider block is wrong or points to another tenant | Confirm the tenant ID in the Entra admin center and check that the metadata endpoint in Superset configuration uses that same tenant |
| Token request returns invalid client | Client secret is expired, mistyped or was copied with extra whitespace | Create a new secret in the app registration, store it in your secret manager, and redeploy Superset with the new value |
| Groups missing from the user's session | Group claim is not included in the token, or the app is not configured to emit group membership | Enable group claims in the token configuration and confirm the claim appears in a test token before changing role mapping |
| Group claim replaced by an overage indicator | The user belongs to more groups than the token can carry, so Entra ID does not send the list | Limit the groups emitted to assigned security groups, or design role assignment so fewer groups are needed per user |
| User signs in but lacks expected Superset permissions | AUTH_ROLES_MAPPING is incomplete, group object IDs are mismatched, or the default role is too narrow | Compare the group object IDs in the token with the mapping keys and add the missing entries, then have the user sign out and back in |
| User is blocked with an access denied message from Microsoft | The user is not assigned to the enterprise application and assignment is required | Assign the user or a group to the application, or confirm the assignment requirement is set as intended |
| Browser loops between Superset and Microsoft login | Callback uses HTTP while the public URL is HTTPS, or a proxy strips headers, or a changed SECRET_KEY invalidates existing sessions | Set the public URL and proxy headers to match the external scheme, then clear browser cookies and confirm SECRET_KEY handling is consistent |
Questions about effort, cost and ownership of Entra ID SSO for Superset
What drives the effort of setting up Entra ID sign-in for Superset?
The main drivers are the number of groups you map, how complex your role model is, how many Superset instances you run, whether a staging environment exists, and how your Entra ID tenant is governed. Each group needs a decision about which Superset role it grants, and each instance needs its own app registration, redirect URIs and configuration. A single production instance with a small set of groups and a staging copy is far less work than several instances sharing a tenant with strict change control. Ask your tenant administrator how many groups already exist for Superset-like access and who approves new app registrations, because those answers set the size of the work.
Can our own team set up Entra ID SSO for Superset without a partner?
Yes, if your team has Entra ID application administration skills and has configured Superset before. The work involves creating an app registration, setting redirect URIs and client credentials, deciding how group claims reach Superset, and writing the role mapping in the Superset configuration. Your team should also plan two steps that are easy to skip: keeping a break-glass local admin account that works when the identity provider is unavailable, and testing sign-in, group mapping and sign-out with named test users in a non-production instance before cutting over. If nobody on the team has done this before, a fixed-scope engagement can cover the first build and hand over a runbook.
What recurring work remains after Entra ID SSO goes live?
Recurring work includes rotating the client secret or certificate before it expires, upgrading Superset, and updating role mappings when groups change. Secret rotation is a calendar task owned by whoever manages the app registration, and it should be tracked with the expiry date in your tenant. Superset upgrades follow the project's upgrade guidance: back up the metadata database, run the database upgrade and initialization commands, test in staging first, and check UPDATING.md for breaking changes. Mapping changes follow your access reviews, so someone must own the list of groups and their Superset roles over time. Ask any provider to quote these as ongoing support or as a retainer, separate from the initial build.
What do we need to provide before work starts on Entra ID SSO?
You need to provide tenant administrator access or a named administrator who can create app registrations and grant admin consent, a decision on how groups map to Superset roles, and a set of test users covering each role. You also need a Superset instance to work against, ideally with a staging copy, and access to the place where Superset configuration is deployed. Without a group design decision, the work stalls because each mapping has to be agreed before it can be coded and tested. Confirm with your tenant administrator whether group claims will be sent as IDs or names and whether any group-based restrictions already exist, since both affect the design.
What should a fixed-scope quote for Entra ID SSO list?
A fixed-scope quote should list the instances in scope, the app registrations and redirect URIs to be created, the authentication configuration to be delivered, the group-to-role mapping table, and the break-glass admin procedure. It should also state the test cases used for sign-in, role mapping, sign-out and a denied-access user, plus the documentation and handover sessions. Ask for the assumptions about your tenant, the client decisions required, and the items excluded, such as group-based restrictions beyond the Superset mapping or an upgrade of Superset itself. Any figure for duration or cost should trace back to that written scope.
Who owns the Entra ID app registration and the Superset configuration after handover?
Ownership should be split explicitly and written down. The identity team usually owns the Entra ID app registration, including secrets, consent and expiry dates, while the platform team owns the Superset configuration, the metadata database and upgrades. Business owners should own the group list and the roles each group receives. Without a named owner for each piece, secrets expire unnoticed and orphaned groups keep granting access. Ask your tenant administrator to confirm which group owns the app registration and how changes to it are approved.
Does the group overage limit change the effort of the build?
It can. When a user belongs to many groups, Entra ID may not include every group in the token, so the design has to decide how Superset learns the full group membership. Teams usually choose between limiting the groups assigned to the application, using a smaller set of dedicated access groups, or retrieving memberships through a separate call. Each option has different effort and different operating risk. Your engineers should test a user with a large number of groups before go-live, and your tenant administrator should confirm the current limit and claim behavior for your tenant.
How DeployOpen scopes and delivers Entra ID SSO for Superset
DeployOpen plans and implements Apache Superset single sign-on with Microsoft Entra ID inside your own infrastructure, as a fixed-scope engagement agreed in writing before work starts. The work covers app registration, OIDC configuration, group-to-role mapping, a tested break-glass admin path and handover documentation for your team.
How we scope
- We confirm your Superset version, hosting model and metadata database before agreeing the written scope.
- We list which Entra ID tenants, app registrations and groups are in scope, and who approves them.
- We agree the role mapping design, break-glass procedure and test cases in the written scope before any build begins.
How we build
- We register the Superset application in your Entra ID tenant and configure redirect URIs, secrets and token settings in your environment.
- We configure the OAuth provider block and AUTH_ROLES_MAPPING in your Superset configuration and test sign-in with real group memberships.
- We handle the group overage case by testing the claim behavior your tenant produces and documenting the chosen approach.
How we hand over
- We deliver configuration records, group-to-role mapping tables and the break-glass admin runbook for your operations team.
- We document the test results for sign-in, role assignment, sign-out and admin fallback so your reviewers can repeat them.
- We walk your identity and platform staff through change steps for new groups, secret rotation and Superset upgrades.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped in writing separately from the build.
- We can review group mapping changes and Superset upgrade impacts on login behavior when your retainer covers them.
- We prepare configuration and evidence for your compliance assessments, while independent auditors issue any audit reports.
