How Apache Superset single sign-on with Keycloak works
Superset authenticates through Flask-AppBuilder's OAuth2 support against Keycloak's OpenID Connect endpoints, and Keycloak group membership maps to Superset roles through AUTH_ROLES_MAPPING. The integration is configured in Superset's superset_config.py file, not in a plugin or a separate service. Superset is an Apache Software Foundation project under the Apache License 2.0, and Keycloak is open source under Apache 2.0 and supports OpenID Connect, OAuth 2.0 and SAML 2.0. This means the login path is built from standard components you can inspect and operate yourself, provided your team is comfortable maintaining both a Superset configuration and a Keycloak realm. The Superset side of the flow, the provider block and the role mapping are covered in the sections that follow.
Three pieces must agree for a login to work: the Keycloak realm and client, the OAuth provider block in Superset, and the group claim that carries roles from Keycloak into Superset. The client's redirect URI must match the Superset callback path exactly, and the client secret must be stored where your secret management process can rotate it. Your SECRET_KEY is also part of this chain, because Superset requires one to start and protects the sessions that OAuth creates. Confirm early whether your Keycloak deployment will issue group or role claims in the token, since the mapping depends on that claim being present and named as you expect. Most failed first logins trace back to one of these mismatches rather than to Superset itself.
This page covers how the Superset configuration is wired to Keycloak. It does not assess Keycloak's own audit posture, its hardening, or the controls around its administrators, and DeployOpen does not issue audit reports or attestations. If an auditor will test your identity controls, ask your assessor which evidence they need from Keycloak's configuration, event logging and admin access records, and plan to collect that evidence from your own environment. Keycloak's release cadence also matters for this integration, so check the Keycloak upgrading guide before changing realm or client settings during an upgrade.
What you need before configuring Keycloak login
Keycloak login touches four systems: Superset, its metadata database, Keycloak and the network between them. Confirm each component before you edit any configuration, because most failed SSO rollouts trace back to a missing certificate, an unsupported database version or an endpoint Superset cannot reach.
A running Superset release
Start from a Superset release with documentation for 6.1.0 or later, and confirm the exact version in your environment before you write any provider code. Check the version against the upgrade notes if you are on an older release, since OAuth settings and Flask-AppBuilder behavior can change between versions. Record the version so you can match it to the configuration documentation you follow. Ask your platform team which build runs in staging and which runs in production, because the two must match.
Supported metadata database
Superset stores users, roles and OAuth-linked accounts in its metadata database. Use PostgreSQL 10 to 17 or MySQL 5.7 or 8.x, and do not rely on the SQLite default for a login setup that other people will use. Confirm that the database is backed up and that you can restore it before you change authentication, because role assignments created at login are written there.
A user-specified SECRET_KEY
Superset will not start without a SECRET_KEY that you set yourself. Generate a long random value, store it in your secrets manager and inject it through your deployment configuration rather than committing it to a configuration file. Plan how you will rotate it later, since Superset supports a PREVIOUS_SECRET_KEY for that purpose. Changing the key without a plan signs out every session.
Keycloak with a production database
Run Keycloak on a production database rather than the development file database. PostgreSQL 14 to 18 is among the supported options, and the Keycloak database guide lists others. Confirm the Keycloak release you run, since the current release is 26.8.1 and older releases may have different admin console paths and client settings. Make sure you have a realm admin account that is separate from daily administrative use.
HTTPS on both hostnames
Superset and Keycloak both need HTTPS endpoints with valid certificates that your browsers and servers trust. The OIDC redirect back to Superset and the token exchange depend on it, and mixed or self-signed certificates are a common source of login loops. Confirm the public hostnames, certificate chains and renewal process for each, and decide whether an internal certificate authority is needed for server-to-server calls.
Network paths and an admin account
Superset's server must reach Keycloak's token and userinfo endpoints directly, not only the browser. Test those paths from the Superset container or host with the same DNS and certificate trust that Superset will use. Also confirm you have a Keycloak realm admin and a named Superset admin who can receive a break-glass role, so a misconfigured mapping does not lock everyone out.
Configuring the Keycloak realm, client and Superset provider block
This sequence produces a Keycloak realm and confidential client that issue a groups claim, and a Superset configuration that sends users through Keycloak sign-in and assigns Superset roles from that claim. Each step ends with a check you can run before moving on.
Select or create the Keycloak realm
The Keycloak administrator either selects the realm that already holds your workforce users or creates a dedicated realm for Superset. Keep the realm name, issuer URL and the users and groups you intend to authorize in one written record, because every later setting depends on them. Done means the realm's OpenID Connect discovery document loads in a browser at the realm's well-known configuration path, and the realm's administrators can see the test users you plan to use.
Create the confidential OpenID Connect client
In the realm, the administrator creates an OpenID Connect client with client authentication turned on, so Keycloak issues a client secret that Superset holds on the server side. Set the valid redirect URI to the callback path that Superset's OAuth login uses, built from your public Superset address, and restrict web origins to that same host. Done means the client shows a stored secret and the redirect URI matches the address users will open in their browser exactly, including scheme and port.
Add a groups mapper to the client scope
Add a mapper that places the user's group membership into a named claim, typically
groups, and enable it for both the ID token and the userinfo endpoint. Choose whether to emit full group paths or short group names, and document that choice, because Superset role mapping must match it character for character. Done means that a test user who belongs to a known group receives that group in a decoded token: sign in as the user, capture the token from a test login or the client's evaluate tool, decode it, and confirm the claim lists the expected group.Add the OAUTH_PROVIDERS block to superset_config.py
The Superset administrator adds an entry to
OAUTH_PROVIDERSinsuperset_config.pythat names the provider, sets the client ID and client secret, pointsserver_metadata_urlat the realm's discovery document, and sets theapi_base_urland token and authorize endpoints if your Flask-AppBuilder version requires them. Read the secret from an environment variable or secret store rather than the file itself, and confirm thegroupsclaim name matches the mapper. Done means the configuration file loads without errors in a Superset shell, and the provider name appears in Superset's configuration check.Set authentication type and role mapping
In the same configuration file, set
AUTH_TYPEto the OAuth constant, defineAUTH_USER_REGISTRATIONto control whether users are created at first login and which role they receive by default, and defineAUTH_ROLES_MAPPINGto translate each Keycloak group name into one or more Superset roles. Keep a break-glass local admin account available and tested before enabling the change. Done means the mapping dictionary contains an entry for every group you intend to authorize, and the default role is the least privileged role you accept for a new account.Restart Superset and test sign-in
Restart the Superset web service so the new configuration loads, then open the login page in a private browser window. The tester should sign in through Keycloak with a test user from a mapped group and be redirected back to Superset. Done means the sign-in completes, the user lands on the Superset home page, and the username appears in the user list with the expected role. If sign-in fails, check the redirect URI and the server log for the OAuth callback error before changing other settings.
Confirm roles for each test group
Repeat sign-in with at least one test user from each mapped group and one user from an unmapped group. For each user, confirm in Superset's user list that the roles match the mapping, and that the unmapped user receives only the default role or is refused, depending on your registration setting. Done means every test account shows the role you designed, and the results are recorded so that a later change to the mapping can be retested against the same accounts.
Mapping Keycloak claims and groups to Superset roles
This table lists the Keycloak token values Superset reads at login, the Superset fields they fill, and the settings that connect them to roles. Read each row as a checkpoint: confirm the claim name in a real token first, then align group names with Superset role names before users log in.
| Keycloak value | What it carries | Superset field or setting | What to confirm |
|---|---|---|---|
| Subject (sub) | Stable unique identifier for the user in the realm | Used by Superset to match the OAuth identity to a user record | Confirm the sub claim is present in the ID token or userinfo response your client returns |
| Email claim | User email address, included when the email scope is granted | Email field on the Superset user record, often needed for alerts and reports | Confirm the email scope is assigned to the client and the mapper emits the claim |
| Preferred username | Keycloak login name, usually the value users type at sign-in | Username field on the Superset user record when the provider maps it | Confirm the claim name your provider code reads matches what appears in your token |
| Groups claim | Keycloak group membership, often sent as a list of group paths | Source for role names through AUTH_ROLES_MAPPING | Group paths can start with a leading slash, so strip it before matching; confirm the exact claim name in your token |
| Realm roles claim | Realm-level role names assigned to the user | Alternative source for role names if you map roles instead of groups | Confirm whether your mapper reads realm roles or groups, since a token may carry one, both or neither |
| AUTH_ROLES_MAPPING key | The Keycloak group or role name, written exactly as it appears in the claim | Dictionary key in the Superset configuration that points to one or more Superset roles | Keys are case-sensitive and must match the claim value without the leading slash |
| Default role for new users | Role given to a user who signs in but matches no mapped group | Configured in Superset so first-time users receive a minimal role | Confirm the default is least privilege and that unmapped users cannot reach sensitive datasets |
| Superset role names | Built-in or custom roles such as Admin, Alpha, Gamma or Public | Targets of the mapping; roles must exist in Superset before login | Confirm each target role exists in your Superset instance and carries only the data access you intend |
Securing the client secret, tokens and redirect URIs
The Keycloak client, the Superset provider block and the Superset server settings form one trust chain. Each card below covers one link in that chain, from where the client secret lives to which groups may sign in at all. The Superset hardening and PKCE pages in this group go deeper on their own topics, so this section only covers what changes for the Keycloak login.
Keep the client secret out of source control
The Keycloak client secret lets Superset exchange authorization codes for tokens, so anyone who reads it can impersonate the client. Load it from an environment variable or a secrets manager at container start, not from a superset_config.py file committed to a repository. Check your Git history as well as the current branch, because a secret pasted once and later removed is still exposed. Rotate the secret in Keycloak if you suspect it was ever copied out of your controlled environment.
Register the exact callback URI only
Keycloak checks the redirect URI in each login request against the list configured on the client. Register the full Superset callback path for your host, with no wildcards and no trailing paths that other applications could also use. Keep separate Keycloak clients for development, staging and production so a test redirect never reaches the production realm. Review the list after every change to the public hostname, because an old entry left behind is a quiet way for a login response to reach an unintended place.
Serve every login path over HTTPS
Superset sets session cookies and receives authorization codes through the browser, so the login must never run over plain HTTP. Terminate TLS at your reverse proxy or ingress, redirect HTTP to HTTPS, and confirm that the public URL Superset generates in its redirect matches the HTTPS address. Keycloak should also be reachable only over HTTPS, and its issuer URL in the Superset provider block should use the same scheme. Mixed schemes are a common cause of login loops and of cookies that fail to set.
Set and plan rotation of SECRET_KEY
Superset refuses to start without a user-specified SECRET_KEY, and that key signs session data. Generate a long random value, store it with the other secrets, and never reuse the example value from documentation. When you rotate it, set PREVIOUS_SECRET_KEY to the old value so existing sessions and encrypted data remain readable during the change, then remove the old key after the rotation window closes. Test the rotation in staging first, because a wrong key makes every active session fail at once.
Limit sign-in to approved Keycloak groups
A valid Keycloak account does not automatically need Superset access. Restrict who can authenticate by assigning the Superset client scope or a dedicated group to the users allowed in, and deny the rest at the Keycloak layer rather than relying on Superset to reject them after login. Map only the groups that carry a Superset role, and decide in advance what happens to a user who has no mapped group. Ask your team to confirm how new users are provisioned before the first production login.
Review whether PKCE is needed
PKCE adds a code verifier to the authorization request so a stolen authorization code cannot be redeemed by another client. Whether your Keycloak client needs it depends on how the client is configured and on your own risk review, so confirm the choice with your identity team before go-live. The Superset PKCE page in this group walks through when to enable it and how to test the flow. Record the decision with the client configuration so auditors can see that it was considered.
What happens at logout and session end
Logging out of Superset does not, by itself, end the Keycloak session. Superset clears its own Flask-AppBuilder session when a user logs out, but the Keycloak realm keeps a browser single sign-on session for as long as its settings allow. A user who clicks Log out in Superset and then opens Superset again may be signed back in without seeing a Keycloak login prompt. Treat this as the default until you have tested it. Confirm the behavior on the exact Superset release you run, because the logout path depends on the Flask-AppBuilder version and on whatever logout route your Superset configuration overrides.
Two ways to close the gap need to be tested rather than assumed. The first is to redirect the logout action to the Keycloak OpenID Connect end-session endpoint of your realm, so Keycloak terminates its session as well. This usually requires a custom logout view or override in your Superset configuration, and the post-logout redirect URI must be registered on the Keycloak client. The second is to shorten how long a Keycloak session survives. In the realm settings, review the SSO session idle and SSO session max values, along with the access token lifespan that governs how long a token is valid. Ask your identity team to document these values, then check in a test realm that a logged-out user is prompted again when expected.
Session length in Superset is also bounded by the Superset session settings in superset_config.py, so review those alongside Keycloak. Record the answers to four questions before go-live: what happens to a user whose Keycloak account is disabled while a Superset session is open, how long an idle Superset browser session remains valid, whether the chosen logout method is verified on your target release, and who owns the test evidence. Use a shared workstation scenario and a disabled-account scenario as test cases, and repeat them after each Superset or Keycloak upgrade.
Why Keycloak login to Superset fails
This table lists the failures teams most often hit when wiring Superset to Keycloak over OpenID Connect, with the likely cause and the first check to run for each. Work through the rows in order, since a token or redirect problem often hides behind a later symptom like users landing with no role. Most failures trace back to a mismatch between what Keycloak sends and what Superset expects.
| Symptom | Likely cause | First check |
|---|---|---|
| Redirect URI mismatch error at Keycloak | The valid redirect URI in the Keycloak client does not exactly match the callback URL Superset sends, including scheme, host, port and path | Compare the client's valid redirect URIs in the Keycloak admin console with the callback URL in the browser's address bar during the failed login |
| Discovery or issuer errors at startup or login | The metadata URL points to the wrong realm, or the issuer in the token differs from the one Superset is configured to trust, often because of a public versus internal hostname | Open the realm's OpenID configuration URL in a browser or with curl and compare its issuer value with the one in the provider block |
| Invalid client or unauthorized client response | The client secret in Superset does not match the secret stored for the Keycloak client, or the client is set as public and has no secret | Regenerate or copy the secret from the client's Credentials tab, update the provider configuration and confirm the client authentication setting |
| Login succeeds but no groups appear | The groups claim is missing from the ID or access token because no mapper exposes group membership to the client | Inspect the token contents from a test login and confirm a group membership mapper adds the claim to the tokens Superset uses |
| Users sign in but have no role | Keycloak group names do not match the role names in the role mapping, so no Superset role is assigned and the user gets only default access | Compare the exact group path and name in Keycloak with the keys in the role mapping, including case and any leading slash |
| Token fails validation intermittently | Clock skew between the Superset host and Keycloak makes tokens look not yet valid or expired | Compare UTC time on both servers and confirm both sync with a time service before changing any Superset setting |
| TLS or certificate trust errors on callback | Superset does not trust the certificate chain of the Keycloak endpoint, often an internal certificate authority not added to the container or host trust store | Test the discovery and token endpoints from the Superset host with the same certificate bundle the application uses |
| Users return to a logged-in state after logout | Superset ends its own session but the Keycloak browser session remains, so the next login is silent, or the logout redirect is not configured | Log out, then attempt a fresh login: if it succeeds without a password prompt, check the end-session and post-logout redirect settings on both sides |
Running Keycloak under Superset login over time
Plan the Keycloak side and the Superset side of this login as two products on two release tracks, because each changes on its own schedule. Keycloak has moved to four minor releases a year since version 26.0, and the project says breaking changes in a minor release will be opt-in. That makes minor upgrades less risky than they once were, but opt-in changes still have to be found, so read the release notes for every version you move to and confirm which settings, realm defaults or client options change behavior. Keycloak also runs its database schema migration automatically at startup by default. For a large realm or a shared database, ask your team whether the migration should run as SQL applied by your database administrator instead, as the upgrading guide suggests for large deployments.
If you run the Keycloak Operator, set operator updates to manual approval. The Operator documentation strongly recommends this to avoid upgrades you did not schedule, and it gives your team a point to review the release before the cluster changes. Keep the Keycloak client settings, realm exports and role or group definitions that Superset relies on under version control, so a rebuilt realm can be compared with what Superset expects. Confirm with your Keycloak administrator which backup method covers the realm configuration and the database, and test a restore before you depend on it.
On the Superset side, every upgrade starts with a backup of the metadata database, followed by superset db upgrade and superset init, and a check of UPDATING.md for breaking changes between your current and target versions. Run the upgrade in staging first. After either product changes, whether a Keycloak minor release, a Keycloak schema migration, a Superset upgrade or a change to AUTH_ROLES_MAPPING, test the full login flow in staging: a new user, a returning user, a user whose group changed, a user with no mapped group and the logout path. Record the results so the next change has a baseline to compare against.
Questions buyers ask before configuring Keycloak login for Superset
How much effort does Keycloak login for Superset take, and what drives it?
The effort depends mainly on how mature your Keycloak setup already is and how many groups must map to Superset roles. A single realm with a clean group structure, an existing client pattern and a staging Superset is the lightest case. Effort rises with multiple realms, nested groups, custom protocol mappers, several Superset environments, and a test plan that covers login, role assignment, logout and session expiry. Ask any partner to size the work from a written list of realms, groups, environments and test cases rather than from a single headline figure.
Can our internal team configure Keycloak login for Superset alone?
Often yes, if your team already runs Keycloak and operates Superset, because the core steps are a Keycloak client, an OpenID Connect provider block in Superset's configuration, and an AUTH_ROLES_MAPPING that translates group claims into roles. The gaps usually appear in group design, secret handling, certificate trust between Superset and Keycloak, and logout behavior. Check whether anyone on the team has tested Flask-AppBuilder security configuration before. An outside review of the group design and the test plan can be a practical middle path.
What do we need to provide before the work starts?
Plan to provide the following before work begins:
- Administrative access to the Keycloak realm, or a named administrator who can create clients and mappers
- Decisions on which Keycloak groups or roles map to which Superset roles, and who approves them
- A staging Superset and a staging Keycloak, or a written plan for testing against non-production realms
- Certificates and CA trust for both URLs, including the chain Superset must trust when calling Keycloak
- Named test users for each role and a break-glass administrator account
How long does the work usually take?
Duration follows scope, not a fixed template. A single-environment setup with one realm and a short role list typically moves faster than a project covering production and staging, several realms, many groups and a formal test sign-off. Approval cycles for group design and certificate requests often set the pace more than the configuration itself. Ask for a timeline tied to named milestones and to the decisions your organization must make, and confirm which steps depend on your change windows.
Does Superset's Apache License 2.0 mean there is no license fee for this?
Superset is an Apache Software Foundation project released under the Apache License 2.0, and the project has no paid edition, so the software itself carries no license fee. Keycloak is also licensed under Apache 2.0. Your costs come from the infrastructure that runs both, the people who configure and test them, support or retainer agreements if you want them, and the time your team spends on upgrades and group governance. Confirm any third-party component or hosted service licensing separately with its vendor.
What happens to existing local Superset users after SSO is turned on?
Local Superset accounts are not removed by default when you add an OAuth provider, but their behavior depends on your provider settings and on whether an account's username matches a identity returned by Keycloak. Review how Superset matches users at first login, which accounts keep local passwords, and whether any users will be locked out. Plan a cutover that keeps at least one local administrator for recovery, reassigns roles from Keycloak groups, and documents who keeps access after a role mapping changes. Test this on staging with real account types first.
What breaks most often when Keycloak and Superset are first connected?
The most common failures are a mismatched redirect URI in the Keycloak client, a group claim that is missing from the token, roles that do not match the names in AUTH_ROLES_MAPPING, and a certificate the Superset server does not trust. Logout also surprises teams, because ending the Superset session does not always end the Keycloak session. Confirm the exact redirect and logout URLs in your Keycloak client settings, and test a user who is removed from a group to see whether their access changes at next login.
Official Keycloak and Superset documentation to read first
Before you write any Keycloak client or Superset provider configuration, read the Keycloak server administration guide and the Keycloak blog post on backwards compatibility in releases. The administration guide covers realms, clients, client scopes, protocol mappers and group membership, which are the objects you will configure in Keycloak for this integration. The backwards compatibility post explains how Keycloak handles breaking changes between minor releases, and it matters here because your realm and client settings may behave differently after a Keycloak upgrade. Save the Keycloak version you deploy and check the release notes for that version before you settle the client configuration, since a minor upgrade can change defaults. Use the Keycloak server administration guide as your reference for the Keycloak side of the setup.
The Superset side is governed by the Superset configuration documentation, which defines the OAuth provider block, the role mapping setting and the logout-related options that your superset_config.py must use. Keycloak's OpenID Connect endpoints and Superset's expected provider fields must match exactly, so verify each key name against the documentation for your exact Superset release before you copy any provider block from a tutorial, blog or older forum post. Configuration keys and their defaults have changed between Superset releases, and a block that works on one version can fail silently on another. Confirm the release you run with the Superset configuration documentation, and record that version alongside the Keycloak version in your change record so that a later upgrade starts from a known pairing.
How DeployOpen scopes and delivers Keycloak login for Superset
DeployOpen plans, builds, documents and supports Keycloak login for a self-hosted Apache Superset inside your own infrastructure. Each engagement starts from a written, fixed scope that names the realm, client, role mapping and logout behavior before any configuration begins.
How we scope
- We confirm which Keycloak realm, client and identity sources Superset login will use before work starts.
- The written scope lists how Keycloak groups or roles map to each Superset role and who approves changes.
- We agree in writing how logout, session length and a break-glass local admin account will be handled.
How we build
- We configure the Keycloak client and the Superset OAuth provider block in a staging environment first.
- We test role mapping with representative test users, including users in several groups and users in none.
- We verify logout behavior and confirm the SECRET_KEY and metadata database settings are production-ready.
How we hand over
- You receive documentation of the realm and client settings, the provider configuration and the group-to-role mapping.
- We include a test script and checklist so your team can repeat login and access checks after changes.
- Runbooks cover adding groups, rotating client secrets and recovering access if the identity provider is unavailable.
How we support
- Ongoing support, Keycloak and Superset upgrades and continuous testing are available as a retainer.
- Upgrade work follows a staging-first plan that checks the login flow against each new Keycloak and Superset release.
- Retainer scope and response expectations are set in writing, and any changes to the login setup are documented.
