<article class="blog-post">Keycloak shows up wherever an organisation wants to own its identity layer: on-premise deployments, regulated environments, platforms that broker several upstream directories into one login, or simply teams that prefer open source end to end. Superset fits that stack naturally, and Flask-AppBuilder ships a Keycloak handler so the integration is configuration rather than code.</p>
<p>There is one trap that catches almost everyone. FAB&#8217;s Keycloak handler reads a <code>groups</code> claim from the user info endpoint to decide which Superset roles to assign, and a fresh Keycloak client does not include that claim. Logins succeed, everyone gets the default role, and the failure is silent. This guide fixes that in Step 1 so you never see it.</p>
<p>For the general mechanics of Superset authentication, reverse-proxy settings and the break-glass procedure, see our <a href="https://www.andolasoft.com/blog/okta-sso-apache-superset-setup-guide" target="_blank" rel="noopener">Okta guide</a>; they apply here unchanged. This post covers what is specific to Keycloak. Written against Superset 4.x and Keycloak 24, applicable to Keycloak 17 and later (the versions without the <code>/auth</code> URL prefix).</p>
<h2>Step 1: Create the Keycloak client</h2>
<p>In the Keycloak admin console, inside the realm your users live in:</p>
<ul>
<li>Go to <strong>Clients</strong> and choose <strong>Create client</strong>.</li>
<li><strong>Client type:</strong> OpenID Connect. <strong>Client ID:</strong> <code>superset</code>. Give it a name and description. Next.</li>
<li><strong>Client authentication:</strong> On (this makes it a confidential client with a secret). <strong>Authorization:</strong> Off. Under <strong>Authentication flow</strong>, keep <strong>Standard flow</strong> ticked and untick everything else; Superset only needs the authorization-code flow. Next.</li>
<li><strong>Root URL:</strong> <code>https://superset.example.com</code>. <strong>Valid redirect URIs:</strong> <code>https://superset.example.com/oauth-authorized/keycloak</code>. <strong>Valid post logout redirect URIs:</strong> <code>https://superset.example.com/login/</code>. <strong>Web origins:</strong> <code>https://superset.example.com</code>. Save.</li>
<li>Open the <strong>Credentials</strong> tab and copy the <strong>Client secret</strong>.</li>
</ul>
<p>The last segment of the redirect URI, <code>keycloak</code>, must match the provider <code>name</code> in <code>superset_config.py</code>.</p>
<h3>Add the groups mapper</h3>
<p>This is the step that makes role mapping work.</p>
<ul>
<li>On the client, open <strong>Client scopes</strong> and click the dedicated scope named <code>superset-dedicated</code>.</li>
<li>Choose <strong>Add mapper</strong>, then <strong>By configuration</strong>, then <strong>Group Membership</strong>.</li>
<li><strong>Name:</strong> <code>groups</code>. <strong>Token Claim Name:</strong> <code>groups</code>. <strong>Full group path:</strong> Off (so the claim contains <code>superset-admins</code>, not <code>/bi/superset-admins</code>). <strong>Add to ID token:</strong> On. <strong>Add to access token:</strong> On. <strong>Add to userinfo:</strong> On. Save.</li>
</ul>
<p>FAB reads groups from the <strong>userinfo</strong> endpoint, so &#8220;Add to userinfo&#8221; is the one that matters. Turning the other two on costs nothing and helps debugging.</p>
<p>If you prefer Keycloak <strong>realm roles</strong> or <strong>client roles</strong> to groups, add a <strong>User Realm Role</strong> or <strong>User Client Role</strong> mapper instead, with <strong>Token Claim Name</strong> set to <code>groups</code> so FAB picks it up without a custom security manager. The mapping keys in Superset then become role names rather than group names.</p>
<h3>Create groups and assign users</h3>
<p>Under <strong>Groups</strong>, create <code>superset-admins</code>, <code>superset-analysts</code> and <code>superset-viewers</code>, and add users. If Keycloak brokers an upstream directory (LDAP, Active Directory, another OIDC provider), map the upstream groups into these through the identity provider&#8217;s mappers, so the Superset-facing group names stay stable even if the upstream changes.</p>
<p>Optionally, restrict who can log in at all: under the client&#8217;s <strong>Advanced</strong> tab, or through a client policy, require membership of a <code>superset-users</code> group. Users outside it are refused by Keycloak, which is preferable to being created in Superset with no useful role.</p>
<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

KEYCLOAK_BASE_URL = os.environ["KEYCLOAK_BASE_URL"]   # e.g. https://sso.example.com
KEYCLOAK_REALM = os.environ["KEYCLOAK_REALM"]         # e.g. corp
KEYCLOAK_REALM_URL = f"{KEYCLOAK_BASE_URL}/realms/{KEYCLOAK_REALM}"

AUTH_TYPE = AUTH_OAUTH

OAUTH_PROVIDERS = [
    {
        "name": "keycloak",
        "icon": "fa-key",
        "token_key": "access_token",
        "remote_app": {
            "client_id": "superset",
            "client_secret": os.environ["KEYCLOAK_CLIENT_SECRET"],
            "client_kwargs": {"scope": "openid email profile"},
            "api_base_url": f"{KEYCLOAK_REALM_URL}/protocol/",
            "server_metadata_url": f"{KEYCLOAK_REALM_URL}/.well-known/openid-configuration",
            "access_token_url": f"{KEYCLOAK_REALM_URL}/protocol/openid-connect/token",
            "authorize_url": f"{KEYCLOAK_REALM_URL}/protocol/openid-connect/auth",
            "request_token_url": None,
        },
    }
]

AUTH_USER_REGISTRATION = True
AUTH_USER_REGISTRATION_ROLE = "Gamma"

# Keycloak group (or role) name -&gt; Superset roles
AUTH_ROLES_MAPPING = {
    "superset-admins": ["Admin"],
    "superset-analysts": ["Alpha", "sql_lab"],
    "superset-viewers": ["Gamma"],
}
AUTH_ROLES_SYNC_AT_LOGIN = True

ENABLE_PROXY_FIX = True
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_SAMESITE = "Lax"</code></pre>
</div>
<p>Details worth knowing:</p>
<ul>
<li>The provider name <code>keycloak</code> selects FAB&#8217;s handler for Keycloak 17 and later. For Keycloak 16 and earlier, whose URLs include <code>/auth/realms/...</code>, use the provider name <code>keycloak_before_17</code> and add the <code>/auth</code> prefix to every URL.</li>
<li><code>api_base_url</code> ends at <code>/protocol/</code> because FAB&#8217;s handler requests <code>openid-connect/userinfo</code> relative to it. Get this wrong and the login completes but the profile fetch 404s.</li>
<li>The <code>scope</code> does not need <code>groups</code>; the mapper puts groups into userinfo regardless of scope. If you configured the mapper on a separate client scope rather than the dedicated one, add that scope&#8217;s name here.</li>
<li>FAB&#8217;s Keycloak handler returns <code>preferred_username</code> as the Superset username. Keycloak usernames are stable, so this is a safe default.</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>Realm roles mapped — now what governs dashboards?</h4>
<p>OIDC gets people logged in; role sync, token lifetime, and RBAC design decide what they can see once they&#8217;re in. A Superset Architecture Review covers the part after the login screen.</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 and open the login page. You should see a single &#8220;Sign in with keycloak&#8221; button.</p>
<ul>
<li>Log in as a member of <code>superset-admins</code>. Check <strong>Settings, List Users</strong>: the user should exist with the <code>Admin</code> role.</li>
<li>Confirm the groups claim is actually arriving. In Keycloak, open <strong>Clients, superset, Client scopes, Evaluate</strong>, pick a user and look at <strong>Generated user info</strong>. The <code>groups</code> array should be present. If it is not, the mapper is on the wrong scope or &#8220;Add to userinfo&#8221; is off.</li>
<li>Log in as a viewer from a private window and confirm the restricted view.</li>
<li>Move a user between groups, sign out and in, and confirm the role changes.</li>
</ul>
<h2>Troubleshooting</h2>
<div class="table-responsive">
<table>
<thead>
<tr>
<th>Symptom</th>
<th>Cause</th>
<th>Fix</th>
</tr>
</thead>
<tbody>
<tr>
<td>Every user gets the Gamma role only</td>
<td>No <code>groups</code> claim in userinfo</td>
<td>Add the Group Membership mapper with &#8220;Add to userinfo&#8221; on; check with Client scopes, Evaluate</td>
</tr>
<tr>
<td>Group names in the claim look like <code>/bi/superset-admins</code></td>
<td>Full group path is on</td>
<td>Turn it off, or use the full path as the key in <code>AUTH_ROLES_MAPPING</code></td>
</tr>
<tr>
<td><code>Invalid parameter: redirect_uri</code> from Keycloak</td>
<td>Redirect URI not in the client&#8217;s valid list, or scheme mismatch</td>
<td>Add the exact URI; enable <code>ENABLE_PROXY_FIX</code></td>
</tr>
<tr>
<td>404 after login, log mentions <code>userinfo</code></td>
<td><code>api_base_url</code> wrong, usually missing <code>/protocol/</code> or using the pre-17 <code>/auth</code> prefix</td>
<td>Correct the URL or switch to <code>keycloak_before_17</code></td>
</tr>
<tr>
<td><code>invalid_client</code></td>
<td>Client authentication off (public client), or wrong secret</td>
<td>Turn client authentication on and copy the secret from Credentials</td>
</tr>
<tr>
<td><code>mismatching_state</code></td>
<td>Session cookie not sent on callback</td>
<td><code>SESSION_COOKIE_SAMESITE = "Lax"</code>, <code>SESSION_COOKIE_SECURE</code> matching the scheme</td>
</tr>
<tr>
<td>Login loops back to Keycloak</td>
<td>Keycloak requires a consent or a required action (update password, verify email) the user has not completed</td>
<td>Complete the action in Keycloak, or disable consent required on the client</td>
</tr>
<tr>
<td>Works for local Keycloak users, not for brokered users</td>
<td>Upstream identity provider mappers do not populate the groups</td>
<td>Add identity provider mappers to place brokered users into the Superset groups</td>
</tr>
</tbody>
</table>
</div>
<h2>Operational notes</h2>
<ul>
<li><strong>Realm boundaries.</strong> Superset can only authenticate users from the realm in its URLs. If different business units live in different realms, either broker them into one realm or configure one provider entry per realm in <code>OAUTH_PROVIDERS</code>; the login page then shows one button per realm.</li>
<li><strong>Session length.</strong> Keycloak&#8217;s SSO session settings and Superset&#8217;s <code>PERMANENT_SESSION_LIFETIME</code> are independent. Disabling a user in Keycloak stops new Superset logins but not the current session; keep Superset&#8217;s lifetime short.</li>
<li><strong>Back-channel logout.</strong> Keycloak can notify clients when a user logs out centrally. FAB does not consume that notification, so central logout does not end the Superset session. Rely on session lifetime instead.</li>
<li><strong>Secret rotation.</strong> Regenerate the client secret in Keycloak and update Superset&#8217;s environment in one change window. There is no grace period for two valid secrets on a single client.</li>
<li><strong>Air-gapped deployments.</strong> Everything here works without internet access. Both Superset and Keycloak must resolve each other&#8217;s hostnames, and Superset must trust the certificate Keycloak presents. Mount your internal CA bundle into the Superset container and point <code>REQUESTS_CA_BUNDLE</code> at it.</li>
</ul>
<h2>Frequently Asked Questions</h2>
<h3>Why does every Superset user get the Gamma role after Keycloak SSO?</h3>
<p>Because the <code>groups</code> claim is missing from the userinfo response. A fresh Keycloak client does not emit it, Flask-AppBuilder finds no role keys, nothing matches <code>AUTH_ROLES_MAPPING</code>, and <code>AUTH_USER_REGISTRATION_ROLE</code> applies to everyone. Add the Group Membership mapper to the client&#8217;s dedicated scope with <strong>Add to userinfo</strong> turned on, then confirm it under <strong>Clients, superset, Client scopes, Evaluate</strong> before changing anything in Superset.</p>
<h3>Which provider name should I use for Keycloak in OAUTH_PROVIDERS?</h3>
<p>Use <code>keycloak</code> for Keycloak 17 and later, whose URLs are <code>/realms/&lt;realm&gt;/...</code>. For Keycloak 16 and earlier, use <code>keycloak_before_17</code> and add the <code>/auth</code> prefix to every URL. The provider name also has to match the last segment of the redirect URI registered on the client, so changing one means changing the other.</p>
<h3>Can Superset authenticate users from more than one Keycloak realm?</h3>
<p>Not through a single provider entry, because the realm is baked into the URLs. Either broker the other directories into one realm through Keycloak&#8217;s identity provider mappers, which is the cleaner option, or add one entry per realm to <code>OAUTH_PROVIDERS</code>. The second approach puts one sign-in button per realm on the Superset login page, which users find confusing beyond two.</p>
<h3>Does Keycloak back-channel logout end the Superset session?</h3>
<p>No. Keycloak can notify clients when a user logs out centrally, but Flask-AppBuilder does not consume that notification, so a central logout leaves the Superset session running until it expires. The same applies to disabling a user: new logins stop immediately, the current session does not. Keep <code>PERMANENT_SESSION_LIFETIME</code> to a working day or less and treat it as the real revocation window.</p>
<h2>Build It With Andolasoft</h2>
<p>Once Superset trusts Keycloak, the role mapping above becomes the front door to everything else: which roles reach which datasets, how row-level security narrows them, and who gets SQL Lab. A <a href="https://www.andolasoft.com/what-we-do/superset-architecture-review" target="_blank" rel="noopener">Superset Architecture Review</a> looks at authentication, RBAC and RLS together, alongside caching, async queries and upgrade readiness, and delivers a written report in five working days. For a self-hosted platform that stays patched and monitored without your team on call, air-gapped deployments included, see <a href="https://www.andolasoft.com/what-we-do/superset-managed-support" target="_blank" rel="noopener">Managed Support</a>, and for the wider set of controls, our post on <a href="https://www.andolasoft.com/blog/data-governance-and-security-best-practices-for-superset-deployments" target="_blank" rel="noopener">governance and security for Superset deployments</a>.</p>
<p>If you are running Keycloak in front of a self-hosted Superset and the group mapping has never quite been right, <a href="https://www.andolasoft.com/contact-us" target="_blank" rel="noopener">talk to us</a>. We will trace a real login end to end, show you where the claim is being lost, and give you a fixed-scope plan for the role model behind it.</p>
</article>


How to Set Up Keycloak SSO for Apache Superset (OpenID Connect)

Table of Contents

Related Articles

For Sales