<article class="blog-post">If your organisation runs on Microsoft 365, Entra ID (the service formerly called Azure Active Directory) is already the source of truth for who works there and what they may access. Superset should read from it rather than keeping its own list of passwords. Flask-AppBuilder, the framework under Superset, has an Azure OAuth handler built in, so the setup is configuration rather than code.</p>
<p>This guide is the Entra-specific companion to our <a href="https://www.andolasoft.com/blog/okta-sso-apache-superset-setup-guide" target="_blank" rel="noopener">Okta SSO guide</a>. The general mechanics of Superset authentication, the reverse-proxy settings and the break-glass advice are the same and are not repeated in full here. What differs with Entra is the app registration, the way roles reach Superset, and the errors you will see.</p>
<p>The configuration applies to Superset 2.1 through 4.x, written against 4.x.</p>
<h2>Groups or app roles?</h2>
<p>Entra can put either the user&#8217;s <strong>group memberships</strong> or their <strong>app roles</strong> into the token. Flask-AppBuilder&#8217;s Azure handler reads the <code>roles</code> claim, which is app roles, and uses it as the list of keys to match against <code>AUTH_ROLES_MAPPING</code>.</p>
<p>App roles are also the better design for Superset:</p>
<ul>
<li><strong>No overage problem.</strong> Entra stops emitting the groups claim when a user is in more than a couple of hundred groups and replaces it with an overage indicator. Large organisations hit this routinely. App roles are specific to your application and never overflow.</li>
<li><strong>Assignment lives on the application.</strong> You assign a group or a user to an app role in the Superset enterprise application. The Entra admin sees exactly who can reach Superset and as what, without decoding group names.</li>
<li><strong>Role names are yours.</strong> <code>Superset.Admin</code>, <code>Superset.Analyst</code>, <code>Superset.Viewer</code> are clearer than a security group created five years ago for something else.</li>
</ul>
<p>So this guide uses app roles. If you must use groups, the section near the end explains what to change.</p>
<h2>Step 1: Register the application</h2>
<p>In the Entra admin centre:</p>
<ul>
<li>Go to <strong>Identity, Applications, App registrations</strong> and choose <strong>New registration</strong>.</li>
<li>Name it &#8220;Superset BI&#8221;. Under <strong>Supported account types</strong> choose <strong>Accounts in this organizational directory only</strong> (single tenant).</li>
<li>Under <strong>Redirect URI</strong> select <strong>Web</strong> and enter <code>https://superset.example.com/oauth-authorized/azure</code>. The final segment must match the provider name in <code>superset_config.py</code>, which is <code>azure</code> in this guide. Entra compares redirect URIs case-sensitively and exactly, including trailing slashes.</li>
<li>Register, then note the <strong>Application (client) ID</strong> and <strong>Directory (tenant) ID</strong> from the Overview page.</li>
<li>Under <strong>Certificates &amp; secrets</strong>, create a client secret. Copy the <strong>value</strong> immediately; it is shown once. Set a calendar reminder for its expiry, because an expired secret is a total login outage.</li>
<li>Under <strong>Authentication</strong>, confirm <strong>ID tokens</strong> is ticked under implicit grant and hybrid flows. Superset uses the authorization-code flow, but FAB decodes the ID token for the user&#8217;s profile, so it must be issued.</li>
<li>Under <strong>Token configuration</strong>, add the optional claims <code>email</code>, <code>family_name</code>, <code>given_name</code>, <code>preferred_username</code> and <code>upn</code> to the ID token. This ensures FAB has a username and a display name even for guest or unusual accounts.</li>
</ul>
<h3>Define app roles</h3>
<ul>
<li>Under <strong>App roles</strong>, choose <strong>Create app role</strong>.</li>
<li>Create three roles with <strong>Allowed member types</strong> set to <strong>Users/Groups</strong>:</li>
</ul>
<div class="table-responsive">
<table>
<thead>
<tr>
<th>Display name</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Superset Admin</td>
<td><code>Superset.Admin</code></td>
<td>Full administration</td>
</tr>
<tr>
<td>Superset Analyst</td>
<td><code>Superset.Analyst</code></td>
<td>Build charts and dashboards, run SQL</td>
</tr>
<tr>
<td>Superset Viewer</td>
<td><code>Superset.Viewer</code></td>
<td>View permitted dashboards</td>
</tr>
</tbody>
</table>
</div>
<p>The <strong>Value</strong> is what appears in the token and what <code>AUTH_ROLES_MAPPING</code> matches.</p>
<h3>Assign users and groups</h3>
<ul>
<li>Go to <strong>Identity, Applications, Enterprise applications</strong>, open &#8220;Superset BI&#8221;, then <strong>Users and groups</strong>.</li>
<li>Add your existing security groups, assigning each to one app role. A user can hold several roles by being in several groups.</li>
<li>Under <strong>Properties</strong>, set <strong>Assignment required</strong> to <strong>Yes</strong>. Anyone not assigned is refused by Entra before Superset is involved, which is the behaviour you want.</li>
</ul>
<h2>Step 2: Configure Superset</h2>
<div class="code-block">
<div class="code-header">python</div>
<pre><code class="language-python">import os
from flask_appbuilder.security.manager import AUTH_OAUTH

AZURE_TENANT_ID = os.environ["AZURE_TENANT_ID"]
AZURE_AUTHORITY = f"https://login.microsoftonline.com/{AZURE_TENANT_ID}"

AUTH_TYPE = AUTH_OAUTH

OAUTH_PROVIDERS = [
    {
        "name": "azure",
        "icon": "fa-windows",
        "token_key": "access_token",
        "remote_app": {
            "client_id": os.environ["AZURE_CLIENT_ID"],
            "client_secret": os.environ["AZURE_CLIENT_SECRET"],
            "api_base_url": f"{AZURE_AUTHORITY}/oauth2",
            "client_kwargs": {
                "scope": "openid profile email User.Read",
            },
            "request_token_url": None,
            "access_token_url": f"{AZURE_AUTHORITY}/oauth2/v2.0/token",
            "authorize_url": f"{AZURE_AUTHORITY}/oauth2/v2.0/authorize",
            "jwks_uri": f"{AZURE_AUTHORITY}/discovery/v2.0/keys",
        },
    }
]

AUTH_USER_REGISTRATION = True
AUTH_USER_REGISTRATION_ROLE = "Gamma"

# Entra app role value -&gt; Superset roles
AUTH_ROLES_MAPPING = {
    "Superset.Admin": ["Admin"],
    "Superset.Analyst": ["Alpha", "sql_lab"],
    "Superset.Viewer": ["Gamma"],
}
AUTH_ROLES_SYNC_AT_LOGIN = True

# Proxy and cookie settings (same as any OAuth deployment behind TLS termination)
ENABLE_PROXY_FIX = True
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_SAMESITE = "Lax"</code></pre>
</div>
<p>What is specific to Entra here:</p>
<ul>
<li>The provider <code>name</code> must be <code>azure</code> for FAB&#8217;s built-in handler to recognise it and decode the ID token correctly.</li>
<li>The URLs are the <strong>v2.0 endpoints</strong> for your tenant. Do not use the <code>common</code> tenant unless you intend to accept users from any Entra directory, which for an internal BI tool you almost certainly do not.</li>
<li><code>jwks_uri</code> is what FAB uses to verify the ID token signature. It must be the tenant&#8217;s discovery keys endpoint.</li>
<li>The <code>roles</code> claim is read automatically from the ID token by FAB&#8217;s Azure handler; nothing extra to configure.</li>
</ul>
<style>
.as-inline-cta{display:flex;align-items:stretch;border-radius:14px;overflow:hidden;<br />
background:#eaf4f6;border:1px solid #dee7ea;margin:32px 0}<br />
.as-inline-cta__icon{flex:0 0 128px;background-color:#1aa9ca;<br />
background-image:radial-gradient(rgba(255,255,255,.35) 1.4px,transparent 1.4px);<br />
background-size:11px 11px;display:flex;align-items:center;justify-content:center;padding:20px}<br />
.as-inline-cta__icon span{width:64px;height:64px;border-radius:50%;background:#fff;<br />
display:flex;align-items:center;justify-content:center;box-shadow:0 2px 6px rgba(0,0,0,.12)}<br />
.as-inline-cta__icon svg{width:28px;height:28px;stroke:#0f7f9c;fill:none;stroke-width:2;<br />
stroke-linecap:round;stroke-linejoin:round}<br />
.as-inline-cta__body{padding:22px 28px;display:flex;flex-direction:column;justify-content:center;gap:8px}<br />
.as-inline-cta__body h4{font-size:19px;font-weight:700;color:#1e2246;margin:0}<br />
.as-inline-cta__body p{font-size:14.5px;line-height:1.6;color:#45506b;margin:0;max-width:52ch}<br />
.as-inline-cta__link{display:inline-flex;align-items:center;gap:5px;font-size:14.5px;<br />
font-weight:700;color:#0f7f9c;text-decoration:none;width:max-content}<br />
.as-inline-cta__link svg{width:16px;height:16px;stroke:currentColor;fill:none;stroke-width:2.4;<br />
stroke-linecap:round;stroke-linejoin:round}<br />
.as-inline-cta__link:hover{text-decoration:underline}<br />
@media (max-width:560px){.as-inline-cta{flex-direction:column}<br />
.as-inline-cta__icon{flex:0 0 auto;width:100%;padding:16px 0}}<br />
</style>
<div class="as-inline-cta">
<div class="as-inline-cta__icon"></div>
<div class="as-inline-cta__body">
<h4>App roles chosen — RBAC design is next</h4>
<p>Entra ID settles who can log in; a Superset Architecture Review settles what capability and data-domain roles they land in, so access control doesn&#8217;t get bolted on ad hoc later.</p>
<p><a class="as-inline-cta__link" href="https://www.andolasoft.com/what-we-do/superset-architecture-review" target="_blank" rel="noopener">Book a Superset Architecture Review</a></p>
</div>
</div>
<h2>Step 3: Test</h2>
<p>Restart Superset. The login page shows a single &#8220;Sign in with azure&#8221; button.</p>
<ul>
<li>Sign in as a member of the admin group. Confirm the Admin menu is visible and the user appears in <strong>Settings, List Users</strong> with the <code>Admin</code> role.</li>
<li>In a private window, sign in as a viewer. Confirm only permitted dashboards appear.</li>
<li>Move a user between groups in Entra, sign them out and in. Roles should change, which confirms <code>AUTH_ROLES_SYNC_AT_LOGIN</code>.</li>
<li>Try a user who is not assigned to the application. Entra should refuse with an &#8220;assignment required&#8221; message before reaching Superset.</li>
</ul>
<h2>Entra-specific troubleshooting</h2>
<div class="table-responsive">
<table>
<thead>
<tr>
<th>Symptom</th>
<th>Cause</th>
<th>Fix</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>AADSTS50011: The redirect URI ... does not match</code></td>
<td>Redirect URI mismatch, often case or trailing slash</td>
<td>Copy the URI exactly; enable <code>ENABLE_PROXY_FIX</code> so Superset sends <code>https://</code></td>
</tr>
<tr>
<td><code>AADSTS7000215: Invalid client secret</code></td>
<td>Secret value copied wrongly, or the secret ID instead of the value</td>
<td>Create a new secret and copy the <strong>value</strong> column</td>
</tr>
<tr>
<td><code>AADSTS700016: Application not found in the directory</code></td>
<td>Wrong tenant ID in the URLs</td>
<td>Use the Directory (tenant) ID from the app Overview page</td>
</tr>
<tr>
<td><code>AADSTS50105: The signed in user is not assigned to a role</code></td>
<td>Assignment required is on and the user is unassigned</td>
<td>Assign the user or their group under Enterprise applications</td>
</tr>
<tr>
<td>Everyone gets the Gamma role</td>
<td>App roles not defined, or user assigned to the app without a role</td>
<td>Define app roles and assign groups to specific roles</td>
</tr>
<tr>
<td>Login works, user has no name or email</td>
<td>Optional claims not configured</td>
<td>Add <code>email</code>, <code>given_name</code>, <code>family_name</code>, <code>preferred_username</code> under Token configuration</td>
</tr>
<tr>
<td><code>mismatching_state</code> error</td>
<td>Session cookie not returned on callback</td>
<td><code>SESSION_COOKIE_SAMESITE = "Lax"</code>, <code>SESSION_COOKIE_SECURE</code> matching the scheme</td>
</tr>
<tr>
<td>Logins fail on a Monday morning</td>
<td>Client secret expired over the weekend</td>
<td>Rotate the secret; set the expiry reminder you skipped last time</td>
</tr>
</tbody>
</table>
</div>
<h2>If you must use groups instead of app roles</h2>
<p>Some organisations mandate group-based access for all applications. Two changes:</p>
<ul>
<li>In the app registration under <strong>Token configuration</strong>, add a <strong>groups claim</strong> to the ID token. Choose <strong>Groups assigned to the application</strong> rather than all security groups, which sidesteps the overage problem for most tenants.</li>
<li>Override <code>oauth_user_info</code> in a custom security manager so that <code>role_keys</code> reads the <code>groups</code> claim. Entra emits group <strong>object IDs</strong>, not names, so the keys in <code>AUTH_ROLES_MAPPING</code> become GUIDs:</li>
</ul>
<div class="code-block">
<div class="code-header">python</div>
<pre><code class="language-python">import jwt
from superset.security import SupersetSecurityManager


class EntraGroupsSecurityManager(SupersetSecurityManager):
    def oauth_user_info(self, provider, response=None):
        if provider != "azure":
            return super().oauth_user_info(provider, response)
        id_token = response["id_token"]
        claims = jwt.decode(id_token, options={"verify_signature": False})
        return {
            "username": claims.get("preferred_username") or claims.get("upn") or claims["oid"],
            "first_name": claims.get("given_name", ""),
            "last_name": claims.get("family_name", ""),
            "email": claims.get("email") or claims.get("preferred_username", ""),
            "role_keys": claims.get("groups", []),
        }


CUSTOM_SECURITY_MANAGER = EntraGroupsSecurityManager

AUTH_ROLES_MAPPING = {
    "5d2f9c1a-...-admins-group-object-id": ["Admin"],
    "8b7e4a3c-...-analysts-group-object-id": ["Alpha", "sql_lab"],
}</code></pre>
</div>
<p>The signature is not re-verified here because Authlib has already validated the token during the exchange; the decode is only to read claims. Keep a comment saying so, or the next reviewer will flag it.</p>
<h2>Operational notes</h2>
<ul>
<li><strong>Secret rotation</strong> is the main recurring task. Entra client secrets expire at 6, 12 or 24 months. Put the expiry in the same calendar as your TLS certificates.</li>
<li><strong>Conditional Access</strong> policies in Entra (MFA, compliant device, location) apply to Superset automatically, which is a strong argument for SSO in regulated environments.</li>
<li><strong>Deactivating a user</strong> in Entra blocks new logins immediately. Existing Superset sessions last until <code>PERMANENT_SESSION_LIFETIME</code>; keep it to a working day or less.</li>
<li><strong>Service accounts</strong> that used password login against the Superset API need another path once <code>AUTH_TYPE</code> changes. Plan for it before the cutover.</li>
</ul>
<h2>Frequently Asked Questions</h2>
<h3>Should Superset roles come from Entra ID groups or app roles?</h3>
<p>App roles, in almost every case. Flask-AppBuilder&#8217;s Azure handler reads the <code>roles</code> claim, which is populated by app roles, and matches it against <code>AUTH_ROLES_MAPPING</code> without any custom code. App roles also avoid the groups overage problem: Entra stops emitting the groups claim entirely once a user belongs to more than a couple of hundred groups, and replaces it with an overage indicator that Superset cannot use. Groups remain possible, but they need a custom security manager and group object IDs as mapping keys.</p>
<h3>Why do all my users land in the Gamma role after Entra ID SSO?</h3>
<p>Either no app roles are defined on the registration, or users are assigned to the enterprise application without being assigned to a specific role. Superset is doing what it was told: no <code>roles</code> claim arrives, nothing matches <code>AUTH_ROLES_MAPPING</code>, and <code>AUTH_USER_REGISTRATION_ROLE</code> applies. Check the claim first, by decoding the ID token from a test login, before changing any Superset configuration.</p>
<h3>Why does Entra return AADSTS50011 when the redirect URI looks correct?</h3>
<p>Entra compares redirect URIs exactly, including case and trailing slashes, and the URI Superset sends is built from the request it received. Behind a TLS-terminating proxy, Superset sends <code>http://</code> unless <code>ENABLE_PROXY_FIX = True</code> is set, so a URI registered as <code>https://superset.example.com/oauth-authorized/azure</code> never matches. Set the proxy fix, then copy the URI character for character.</p>
<h3>Do Entra Conditional Access policies apply to Apache Superset?</h3>
<p>Yes. Because the login happens at Entra rather than in Superset, MFA, compliant-device and named-location policies are enforced before a token is ever issued, and Superset inherits them without configuration. That inheritance is one of the stronger arguments for putting Superset behind SSO in a regulated environment. The limit is session lifetime: revoking access in Entra blocks new logins immediately but does not terminate an existing Superset session, so keep <code>PERMANENT_SESSION_LIFETIME</code> short.</p>
<h2>Build It With Andolasoft</h2>
<p>Entra ID settles who can log in. The role design it feeds, row-level security, the caching and async query setup and upgrade readiness are the rest of the platform, and a <a href="https://www.andolasoft.com/what-we-do/superset-architecture-review" target="_blank" rel="noopener">Superset Architecture Review</a> checks all of them in five working days with a written report. If the platform should simply be someone else&#8217;s problem, <a href="https://www.andolasoft.com/what-we-do/superset-managed-support" target="_blank" rel="noopener">Managed Support</a> covers patching, monitoring and the secret-rotation reminders that prevent a Monday-morning outage. For the wider set of controls around a deployment, see <a href="https://www.andolasoft.com/blog/data-governance-and-security-best-practices-for-superset-deployments" target="_blank" rel="noopener">governance and security best practices for Superset</a>.</p>
<p>If you are putting Superset behind Entra ID and would rather settle the role model at the same time than six months later, <a href="https://www.andolasoft.com/contact-us" target="_blank" rel="noopener">talk to us</a>. We will review your app registration, the claims it emits and your current Superset roles, and give you a fixed-scope plan to a deployment your security team can sign off.</p>
</article>


How to Set Up Microsoft Entra ID (Azure AD) SSO for Apache Superset

Table of Contents

Related Articles

For Sales