Apache Superset single sign-on with Okta

How Superset single sign-on with Okta works

If your team runs Superset and wants Okta to own sign-in and group membership, the supported path is OAuth2 through Flask-AppBuilder, which Superset is built on, using an OpenID Connect provider. Superset redirects users to Okta, receives the identity assertion back, and creates or updates the local user. Group membership then decides which Superset roles that user receives, through AUTH_ROLES_MAPPING. Okta stays the source of truth for who can sign in and which groups they belong to, while Superset remains the source of truth for what each role can see and do inside the application.

The Okta-side details are the part to confirm before you commit to a design. The Superset configuration documentation, linked from this page's references, describes the OAuth provider block, the supported provider types and how group values from the token are matched to roles. Okta's current administration console determines how an application is created, which scopes can be granted and how groups are exposed to the application. Do not assume a particular claim name, scope string or console screen from another guide. Record the exact claim that carries group names in your tenant, and check that the group values you map are the ones Okta actually sends, including case and any prefixes.

Plan for two risks early. First, if a group claim is missing or empty at login, a user may be created with default roles or none, so test a user from each group and a user in no group. Second, Superset's local user record persists after Okta removes access, so the deprovisioning steps covered later in this page need to be designed alongside sign-in, not added afterward. Confirm with your Superset version's documentation how role sync happens at each login, because that behavior determines how quickly a removed group takes effect.

What you need before you start Superset SSO with Okta

Most Okta sign-in problems trace back to a missing prerequisite rather than the OIDC configuration itself. The items below cover the Superset release, the metadata database, secrets, network, admin access and testing that must be settled before any Okta application is created.

A supported Superset release

Pin a current release line only after you confirm it on the PyPI and GitHub release pages, since the newest line may still be a pre-release. Read the upgrade notes for the version you choose, because OIDC settings and role names can change between major versions. Record the exact version in your deployment inventory so the Okta callback configuration matches the instance you test and promote.

A production metadata database

Superset stores users, roles and dashboard definitions in its metadata database, and that database holds the local accounts your break-glass plan depends on. Use PostgreSQL 10 to 17 or MySQL 5.7 or 8.x, as listed in the configuration documentation. The SQLite default and the Docker Compose PostgreSQL container are not suitable for production, so plan a managed or hardened database with backups before enabling SSO.

A user-specified SECRET_KEY

Superset refuses to start without a SECRET_KEY that you set yourself, and that key signs session cookies. Generate it with a cryptographic random source, store it in your secrets manager and inject it at deploy time rather than committing it to configuration files. Plan how you will rotate it using PREVIOUS_SECRET_KEY so that rotation does not force every user to sign in again at once.

An Okta org with admin rights

You need an Okta administrator who can create OIDC applications, manage groups and assign them to applications. Confirm who owns the Okta tenant, which authorization server Superset will use, and whether your organization requires change approval for new application integrations. Create a dedicated test group in Okta now, so the groups claim can be verified in staging before any production user is affected.

HTTPS and a trusted certificate

Okta redirects users back to the Superset URL, so that URL must use HTTPS with a certificate browsers trust, and the redirect URI must match exactly, including scheme, host and path. Decide on the public or internal hostname first, since changing it later means updating the Okta application and any bookmarks. Confirm that your load balancer forwards the original scheme so Superset builds correct callback addresses.

A break-glass admin and staging

Create at least one local break-glass administrator in the metadata database before you change the login method, and store its credentials in a sealed, audited location. Then run the full Okta flow in a staging instance that mirrors production configuration, including role mapping and a deprovisioning test. Only promote the configuration when a local admin can still sign in and a test user lands with the expected roles.

Configuring the Okta OIDC app and Superset provider

This sequence connects Superset to an Okta OpenID Connect application so users sign in through Okta, group membership arrives with each login, and new users receive a default role. Each step ends with a check that confirms the piece works before the next one depends on it.

Create the OIDC web application in Okta
An Okta administrator creates a new application integration in the Okta admin console, selects OIDC as the sign-in method and chooses the web application type, since Superset runs server-side and can keep a client secret. Set the sign-in redirect URI to the callback path that Flask-AppBuilder uses for your OAuth provider name, built from your Superset base URL, and confirm the exact path in the Flask-AppBuilder OAuth documentation for your Superset version. Assign a test group to the application so that only intended users can sign in. The step is done when the application shows an assigned group and the redirect URI matches your Superset hostname exactly, including scheme and port.
Record the client credentials in a secrets store
Copy the client ID and client secret from the Okta application's general settings and store both in your organization's secrets manager, not in a shared document or source repository. Note the Okta issuer URL for your authorization server, which you will need for the provider block. Restrict read access to the people and service accounts that deploy Superset. The step is done when the secret is retrievable from the store by the deployment pipeline and the Superset host can read it at startup, which you can confirm by loading the value in a test environment without printing it to logs.
Add a groups claim to the token
In the Okta application's sign-on or token settings, add a groups claim that includes the groups you want Superset to map to roles. Choose a filter that matches only the groups prefixed for analytics access so that unrelated groups do not reach Superset. Decide whether the claim goes into the ID token, the userinfo response or both, and make sure the Superset provider block reads from the same place. The step is done when a pilot user signs in and the decoded token or userinfo response shows the groups claim with the expected group names. If the claim is missing, the group-to-role mapping in the next steps will have nothing to match.
Set the OAuth provider block in superset_config.py
Add an OAuth entry to the Superset configuration, setting AUTH_TYPE to the OAuth authentication type and defining the provider with its name, client ID, client secret, the Okta issuer based server metadata URL and the scopes that include openid, email, profile and groups. Load the client ID and secret from environment variables or your secrets store rather than writing them into the file. Confirm the settings against the Superset configuration documentation for your release, since provider keys and the way the OAuth block is structured have specific requirements. The step is done when Superset starts without errors and the login page shows an Okta sign-in option that opens the Okta authorization page.
Set user registration and the default role
Enable AUTH_USER_REGISTRATION so that a first-time Okta user gets a Superset account on login, and set AUTH_USER_REGISTRATION_ROLE to a low-privilege role such as the built-in Gamma role or a role you have created for new users. Keep this default narrow, because every authenticated user from the Okta application receives it before any group mapping is applied. Confirm that the role you pick cannot open data sources that should be restricted. The step is done when a new test user who has no mapped group signs in and sees only the pages and datasets that the default role allows.
Test sign-in with one pilot user
Sign in as a single pilot user who belongs to one Okta group that you intend to map to a Superset role, and verify three things in order: the Okta callback completes without an error page, a Superset user record is created or updated with the expected email address, and the user's roles match the default role at this point because mapping is configured in a later step. Review the Superset application log for any OAuth errors or warnings about missing claims. Record the result for the pilot, including the Superset version and Okta application ID used. The step is done when the pilot signs in repeatably and the logs show no unresolved errors.

Choosing how Okta groups reach Superset

When your organization has a small number of groups that are meant for analytics access, the simplest approach is to assign only those groups to the Superset application in Okta and include the groups claim in the token without a filter. Okta then sends only what you assigned, and the Superset role mapping stays short enough to review by hand. This works well for a pilot or for a team that already keeps analytics access in dedicated groups.

Assignment controls scope: Only users in groups assigned to the Superset app receive those groups in the token, so assignment is the first and most visible control.
Small tokens: A short, fixed list of groups keeps the ID token or access token compact.
Easy review: Security reviewers can compare the assigned groups with the mapping in AUTH_ROLES_MAPPING in one sitting.
Limited filter work: No claim filter is needed, so there is less configuration for your Okta administrators to maintain.
Clear ownership: Application owners and identity administrators know which groups grant access.

Before you rely on this model, confirm in your Okta edition which group claim options are available, and confirm the exact claim name Superset reads in the OAuth provider settings described in the Superset configuration documentation.

When your directory holds thousands of groups, most of which have nothing to do with analytics, sending every group a user belongs to creates oversized tokens and a long, noisy mapping list. A group claim filter limits what Okta includes in the token, typically by name pattern, so only groups with a shared prefix or naming convention reach Superset. The trade-off is that the filter becomes an access rule, so changes to group names can silently change access.

Smaller tokens: Filtering limits the claim to analytics-relevant groups, which reduces the risk of oversized tokens for users with many memberships.
Naming discipline: Filters depend on consistent group names, so a naming standard such as a shared prefix must be agreed and enforced first.
Filter ownership: The filter lives in Okta, so identity administrators control it, and changes need the same review as role mapping changes.
Mapping stays focused: AUTH_ROLES_MAPPING only needs entries for the filtered groups.
Testing burden: Each new group that should grant access must match the filter, so test a representative user from each group after every change.

Ask your Okta administrators which filter types and claim options their edition supports, and confirm with the Superset configuration documentation which claim name the provider reads.

Mapping Okta groups to Superset roles

This table lists each Okta group, the Superset role it maps to through AUTH_ROLES_MAPPING, the access that role grants and who owns the group. Read it as the source of truth for access review: every Okta group should appear once, every Superset role named here must already exist, and the default and break-glass rows cover users who fall outside the mapping.

Okta group or account	Superset role via AUTH_ROLES_MAPPING	Access granted	Group owner
Okta group: superset-admins	Admin	Full administration of Superset, including users, roles, databases and settings. Limit membership to a small platform team.	Platform engineering lead
Okta group: superset-analysts	Alpha	Create and edit charts and dashboards and query connected databases within their row level security rules. Confirm the exact permissions in your Superset version.	Analytics lead
Okta group: superset-viewers	Gamma	Read access to dashboards that have been shared with the role. Confirm which datasets this role can query before rollout.	BI program owner
Users in no mapped Okta group	Default role set by AUTH_USER_REGISTRATION_ROLE (illustrative: Gamma)	Access only to what the default role allows, or no access if the default is restricted. Confirm the default with your security team.	Security team
Break-glass admin account (local, not driven by Okta)	Admin, assigned directly in Superset	Emergency access when Okta or the OIDC connection is unavailable. Store credentials under dual control and test the login periodically.	CISO delegate or security operations

Securing the Okta login for Superset

The Okta login is only as strong as the settings around it. The cards below cover where the client secret lives, which redirect URIs and groups are allowed, how admin rights are granted, and how you keep a way in if the identity provider fails. Each one is a decision to make and verify before users depend on the integration.

Keep the client secret out of config

The Okta client secret authorizes Superset to exchange login codes, so a copy in plain text in superset_config.py exposes it to anyone who can read the repository or the container image. Load the secret from an environment variable or a secrets manager at runtime, and restrict who can read the deployment manifests. Check that the secret is not printed in startup logs or error pages, and plan a rotation step in Okta that you can run without downtime. Ask your team who holds the rotation runbook.

Enforce HTTPS and exact redirect URIs

Serve Superset only over HTTPS, and register the callback URL in the Okta application as an exact value rather than a wildcard pattern. A loose redirect list lets an attacker who controls a similar hostname receive authorization codes. Confirm that the external URL Superset generates matches the registered callback, including scheme, host and port, behind any reverse proxy or load balancer. Test a mismatched host to confirm the login fails closed.

Limit which Okta groups reach Superset

Assign only the groups that need Superset to the Okta application, so users outside those groups cannot sign in even with valid Okta credentials. Keep this assignment separate from the groups that map to Superset roles, because a group that grants access should be reviewed differently from one that grants admin rights. Ask your identity team how assignments are reviewed and who approves a new group being attached to the app.

Pin admin rights to a small group

Map the Superset Admin role only from a dedicated Okta group with few members, and require an approval step before anyone is added to it. Admin rights in Superset cover users, databases and security settings, so a broad group mapped to Admin turns a routine directory change into a platform compromise. Record who approved each membership and review the group on a fixed schedule. Confirm with your identity team which approval workflow your Okta tenant supports.

Keep a local break-glass admin

Keep one local Superset admin account with a stored, long password and multi-factor protection, sealed for use only when Okta or the callback is unavailable. Without it, an IdP outage, a bad mapping change or an expired secret can lock every administrator out at once. Test the account after each major change, record each use, and rotate its password after every use. Confirm that your Superset version supports the multi-factor setup you choose before relying on it.

Review SECRET_KEY and session settings

Superset requires a user-specified SECRET_KEY to start, and the security hardening guidance covers how it protects session cookies and signed data. Generate a strong value, store it outside the config file, and use PREVIOUS_SECRET_KEY when you rotate it so existing sessions and data can still be read during the change. Review session lifetime, cookie flags and idle timeouts with your security team. Changing the key without this step signs out every user.

What happens when someone leaves the organization

Deactivating a user in Okta stops new sign-ins, but it does not end what is already open. A Superset browser session that was issued before the change can stay valid until it expires, and the Superset user record stays in the metadata database with its roles and any row level security assignments until someone disables it. Your team should treat the Okta deactivation as one step in a leaver process that also covers Superset, not as the whole process. Confirm in your own build how long a Superset session lasts, where the session lifetime is set in superset_config.py, and whether your Flask-AppBuilder version ends sessions when the identity provider reports a change. Do not assume either behavior from the defaults alone.

Next, check four behaviors in your environment before go-live. First, find out what Superset does when a user is removed from an Okta group but still has an active account. With sync at login, the mapped roles should be recalculated the next time the user signs in, so confirm whether the user keeps old roles until that sign-in happens. Second, confirm that an inactive or deactivated Okta user is refused at the OAuth callback, not just at the Okta login page. Third, confirm how the Superset user is marked inactive when that happens, and whether a deactivated account can still be reached through a local password path if one exists. Fourth, name the person who disables the Superset user record in the same ticket that removes the Okta account, and make the Superset step a required line in your offboarding checklist.

Test the leaver scenario in staging before relying on it. Create a test user in Okta, sign in to Superset, open a dashboard, then deactivate the user in Okta and attempt to reload the page and sign in again. Record the time of each step, the result of each attempt, and the state of the Superset user record afterward. Keep these results with the change record, since auditors commonly ask how access was removed and when. Repeat the test after any change to the OIDC provider block, the role mapping or the session settings, because those changes can alter the outcome.

Common Superset Okta login failures and fixes

This table pairs each common Okta sign-in symptom with its likely cause and fix for Superset. Check the Superset logs and the Okta system log before changing configuration, then work down the table by symptom. The main takeaway is that most failures trace to a mismatch between the Okta app settings and the Superset configuration, not to Superset itself.

Symptom	Likely cause	Fix
Redirect error or "redirect_uri mismatch" from Okta	The callback URL registered in the Okta app does not match the URL Superset sends, often because of scheme, host, port or trailing path differences behind a proxy.	Compare the redirect URI in the Okta app with the one in the Superset logs. Correct the Okta sign-in redirect URI or the external URL and proxy headers so they match exactly.
Token exchange fails with invalid client or secret errors	The client secret in the Superset OAuth provider block was rotated in Okta, copied with extra whitespace, or is loaded from the wrong environment variable.	Generate or copy the current client secret from the Okta app, update the secret store used by Superset, restart the web service and retry the sign-in.
No groups in the token, so users get no mapped roles	The groups scope was not requested, the Okta authorization server does not include a groups claim, or the group filter on the Okta app excludes the user's groups.	Confirm the groups scope is in the Superset request, add a groups claim to the authorization server, and check that the assigned groups match the filter. Inspect a sample token in the Okta system log.
Users sign in but land with the default role	AUTH_ROLES_MAPPING does not match the group names in the token, or role sync at login is disabled so existing users keep old roles.	Compare the exact group strings in the token with the mapping keys. Confirm role sync is enabled, sign out fully, then sign in again so the new roles apply.
Group names do not match, differing by case or prefix	Okta group names carry a prefix such as an application or organization tag, or their capitalization differs from the mapping keys.	Standardize group names in Okta or add the exact prefixed, case-sensitive names to the mapping. Test each group with one user before rolling out.
Token rejected as expired or not yet valid	Clock skew between the Superset host and Okta, or a long gap between login and token validation, causes timestamp checks to fail.	Synchronize server time on the Superset hosts with a trusted time source, then retry. Review the Superset logs for timestamp errors before changing token settings.
A user keeps access after removal from Okta	The Superset account remains active locally, and existing sessions or cached sessions continue until they expire or the account is disabled.	Deactivate the user in Superset as part of offboarding, revoke sessions where your setup allows, and confirm the Okta deprovisioning step. Verify that a fresh sign-in is refused.

How much does Superset SSO with Okta cost and how long does it take?

What determines the cost of Superset SSO with Okta?

Cost follows the written scope, and four factors move it most: the number of Okta groups that must map to Superset roles, how much role design is needed, the state of your existing Superset deployment, and how much testing is required before sign-in goes live. A single group mapped to one role for a stable instance is a very different job from twenty groups, custom role permissions and a deployment that has never been upgraded. Ask for each factor to be priced separately so you can see which decisions change the total.

How long does a Superset and Okta single sign-on project usually take?

No duration figure has been established for this work, so treat any number a vendor gives you as a claim to verify against the scope. The schedule depends on the same drivers as cost: how quickly Okta application settings can be approved, how many groups need review with the business, whether Superset's metadata database and secret key are already in order, and how long your test plan takes to run. Ask for a timeline that lists the dependencies on your side, such as Okta admin availability and approval windows, so delays are visible early.

Can our own team set up Superset SSO with Okta without a partner?

Yes, many teams do, provided they have someone comfortable with OpenID Connect, Okta administration and Flask-AppBuilder configuration. The work is configuration rather than new software, but mistakes in the group claim, the role mapping or logout behavior are easy to make and hard to notice until users are locked out or gain too much access. Be honest about whether you have an Okta admin and a Superset admin who can test together, and whether anyone will own the configuration after the first release.

What do we need to provide before the work starts?

Four things make the engagement move: an Okta administrator who can create and change the OIDC application and confirm group assignments, a Superset administrator who can change the configuration and restart the service, a written test plan that lists the users and roles to verify, and a named approver who signs off on the group-to-role mapping. Without the approver, role decisions drift into the implementation and become hard to audit later. Confirm these names and time commitments in the quote before scheduling.

What costs are one-time and what recurs after go-live?

The initial build, mapping design and testing are one-time work. Recurring work includes Superset upgrades, which the upgrade documentation says require a metadata database backup, running superset db upgrade and superset init, testing in staging and checking UPDATING.md for breaking changes. Okta changes also recur: renamed groups, new applications, certificate or secret rotation and policy updates can all break sign-in. Ask whether a support or retainer arrangement covers these, and what response is expected when a group mapping stops working.

What should a written quote for Okta SSO include?

A useful quote lists the scope in writing before work begins, including which Okta groups are in scope, which Superset roles they map to, the environments covered (staging and production), and the test cases used for acceptance. It should name the deliverables, such as the configuration, the mapping document and a logout test record, and state the client responsibilities from the previous question. Most engagements are fixed-scope, so ask what triggers a change request, how changes are priced and what happens if a scope item turns out to be larger than expected.

Does the cost change if we also need to handle deprovisioning and offboarding?

Yes, because deprovisioning is a separate verification problem. Signing a user out of Okta does not automatically remove their Superset account or change roles that were assigned on a previous login, so the design must state how departing users lose access and how quickly. Each additional check, such as confirming a disabled Okta user cannot reach dashboards or that group removal takes effect at the next login, adds test effort. Ask the provider to list the offboarding tests explicitly in the scope so you can judge the effort against your access policy.

How DeployOpen scopes and delivers Superset SSO with Okta

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, and Superset single sign-on with Okta is scoped the same way. The work is agreed in writing before it starts, so your identity, security and data teams know exactly what gets configured, tested and handed over.

How we scope

We confirm your Okta org, Superset deployment model and the Okta groups that should map to Superset roles.
The written scope lists the OIDC application, provider configuration, group mapping and deprovisioning checks to be delivered.
Most engagements are fixed-scope, with deliverables and timelines agreed in writing before any work begins.

How we build

We configure the Okta OIDC application and the Superset provider block in a staging environment first.
We map Okta groups to Superset roles and test each role against accounts that should and should not have access.
We test login, logout and a break-glass local administrator path before anything moves toward production.

How we hand over

You receive the configuration, group mapping table and test results, documented for your own team to maintain.
We document the upgrade steps so later Superset upgrades keep the Okta login working as expected.
The runbook covers how to remove a leaver's access and what to check when a user cannot sign in.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover.
A retainer can cover re-testing group mappings when Okta groups change or Superset is upgraded.
Ask any vendor, including us, to confirm current Okta and Superset behavior against your own environment before go-live.