Why Superset deployments using AUTH_OID must move before the 6.0 upgrade
If your Superset instance logs users in with AUTH_OID, the login method must change before or during the upgrade to 6.0 or later. The reason is that AUTH_OID was removed with Flask-AppBuilder 5 in Superset 6.0, and Superset 6.0 upgraded to Flask-AppBuilder 5.0.0. A deployment that keeps AUTH_TYPE set to the OpenID type will not have a supported login path after the upgrade, so the switch to another authentication type is part of the upgrade work, not an optional cleanup.
Flask-AppBuilder documents that OpenID 2.0 support was removed and that OpenID Connect should be configured through OAuth providers. In practice, the supported paths for this migration are OAuth or OpenID Connect through an identity provider, LDAP, or database login. Superset 6.0.0 was published on December 18, 2025, and 6.1.0 followed on May 13, 2026, according to PyPI. Teams that have not yet started should confirm which Superset release they are targeting and check the breaking change notes in UPDATING.md for that line before they schedule the change.
The decision to make first is which identity source will own each user. Ask your identity team whether the current OpenID provider is already available as an OIDC or OAuth2 issuer, and confirm which group claims it can emit, because those claims drive the AUTH_ROLES_MAPPING entries that replace role assignments previously tied to the OpenID login. Confirm the user identifiers your provider returns, since matching existing Superset user records during the switch depends on them. Plan the change in a staging copy of the metadata database first so that login, role assignment and dashboard ownership can be tested before production users are moved.
What changes in authentication between AUTH_OID and 6.0
This table compares how login worked under AUTH_OID with what applies after Superset 6.0, row by row for the change, its impact and the action you need to take. Read it before the staging build so you can list every login setting and user record that must move before the upgrade reaches production.
| Change | Impact | Action needed |
|---|---|---|
| AUTH_OID removed in 6.0 | Superset 6.0 upgrades Flask-AppBuilder to 5.0.0, which removes the AUTH_OID authentication type | Move every deployment that uses OpenID to another authentication type before upgrading to 6.0 |
| OpenID 2.0 no longer supported | Flask-AppBuilder no longer supports OpenID 2.0, so the old login flow has no replacement in the framework | Choose a replacement provider such as an OAuth2 provider, OpenID Connect provider, LDAP or database login |
| OpenID Connect through OAuth providers | Flask-AppBuilder directs OpenID Connect to be configured as an OAuth provider | Register Superset as a client with your identity provider and configure the OAuth provider entry in Superset |
| Existing login config keys | Settings written for AUTH_OID may no longer apply after the upgrade | Inventory every login-related key in your configuration and confirm each one against the 6.0 configuration documentation in staging |
| User records tied to OpenID claims | Accounts matched to OpenID identifiers may not match the new provider's identity values, so users can be created as duplicates or lose roles | Map the old identifier to the new provider's claim, then test sign-in for sample accounts before cutover |
| AUTH_ROLES_MAPPING for the new provider | Group names from the new provider differ from the OpenID setup, so existing role assignments may not apply | Rebuild the group-to-role mapping for the new provider and verify each role with test users |
How to switch login methods and upgrade in a safe order
This sequence replaces AUTH_OID with a supported login method on the current release first, so the 6.0 upgrade becomes a version change with a tested login path and a known rollback point.
Inventory the current AUTH_OID configuration and users
The platform owner exports the current authentication settings from superset_config.py, including AUTH_TYPE, the OpenID provider list, any custom security manager code, and any AUTH_ROLES_MAPPING or role assignments. Next, the owner counts accounts in the Flask-AppBuilder user tables by login name, email and active status, and records which accounts sign in through OpenID and which use local passwords. This step is done when the team holds a written list of every login path and the number of accounts behind each one, reviewed by someone who owns user access.
Choose the target authentication type
The identity owner and the Superset owner decide where users will sign in after the switch. Flask-AppBuilder documents that OpenID 2.0 support was removed and that OpenID Connect should be configured through OAuth providers, so the usual choices are an OAuth or OIDC provider already run by the organization, LDAP, or database login. The decision record should name the provider, the claim that will carry the username or email, the group claim used for roles, and who approves the mapping. It is done when the identity owner signs off on the provider and the claims.
Build and test the new provider in staging
On the current release, not yet 6.0, the team adds the new authentication settings to a staging copy of the configuration and points it at a test identity provider or test directory. They confirm redirect URIs, client credentials and the secret key handling, and they test sign-in for users in each role group. Because the old and new login methods can be compared on the same version, any failure is clearly a configuration problem. The step is done when test users from each group sign in and receive the expected roles.
Back up the metadata database
Before any production change, the database owner takes a full backup of the Superset metadata database, which holds users, roles and dashboard ownership. The Superset upgrade documentation calls for this backup before migrations run. The team also saves a copy of the production configuration file and the container image tag in use. The step is done when the backup restores successfully into a scratch database and the team has recorded the backup identifier and the configuration copy location.
Apply the new login configuration and run the upgrade
In a staging environment first, the platform engineer applies the new authentication settings, then moves to the target release and runs superset db upgrade followed by superset init, as the upgrade documentation describes. The engineer checks the release notes in UPDATING.md for every version between the current release and the target, because breaking changes can affect configuration beyond login. The same steps are then repeated in production during the agreed change window. The step is done when both commands finish without errors and the application starts on the new release.
Verify logins, role mapping and user matching
The team signs in with test and real accounts from each identity source and checks that each user lands on the existing Superset user record, not a duplicate. They confirm that roles from AUTH_ROLES_MAPPING match the group map, that dashboard ownership and row level security rules still apply, and that users who left the directory cannot sign in. Accounts that did not match are listed and resolved by the access owner. The step is done when every account in the inventory is either matched, deliberately retired or on a documented exception list.
Define rollback points before production cutover
Before production cutover, the team writes down the rollback path: restore the metadata database from the backup taken earlier, restore the saved configuration file, and redeploy the previous container image tag. They rehearse this restore in staging and record how long the restore took in their own environment. The rollback owner and the decision criteria for triggering a rollback are named in advance. This step is done when the rehearsal succeeds and the on-call team has signed the rollback runbook.
Choosing the replacement login: OAuth, OpenID Connect, LDAP or database login
Superset supports OAuth2 providers such as Google and Azure, along with custom OAuth2 servers that use the authorization code flow. Flask-AppBuilder, which Superset is built on, handles the redirect and token exchange, so Superset itself never sees the user's password. This option suits organizations that already run a central identity provider and want one sign-in for their analytics users.
- Provider choice: Confirm that your provider supports the authorization code flow and can return the claims Superset needs to create the user record.
- Consent and app registration: Each provider requires an application registration with redirect URIs that match your Superset hostname. Ask who owns that registration and who can change its secret.
- Group claims: Groups usually arrive as a claim in the token. Check whether your provider includes them by default or only after an administrator enables them.
- Dependence on the provider: If the provider is unavailable, nobody signs in, including administrators. Plan a break-glass account before cutover.
Before committing, confirm with your identity team which claims are issued to Superset and how the provider behaves for users who have left the organization.",
Flask-AppBuilder documents that OpenID 2.0 support was removed and that OpenID Connect should be configured through OAuth providers. In practice, this means your OIDC identity provider is connected to Superset using the OAuth configuration path, not AUTH_OID. Existing OpenID 2.0 deployments therefore need a new provider configuration, and the replacement is an OAuth setup rather than a like-for-like swap.
- Protocol target: Confirm that your identity provider offers OpenID Connect discovery and an authorization code flow compatible with the OAuth provider settings in Flask-AppBuilder.
- Identity mapping: Decide which claim becomes the username or email that Superset matches to existing user records. This decision drives the migration in the user matching step.
- Claim consistency: Test with several real accounts, including accounts with multiple group memberships, before you rely on group mapping.
- Vendor behavior: Check your provider's documentation for token lifetimes and refresh behavior, since these affect how often users are asked to sign in again.
The key question to answer with your identity team is whether your OIDC provider issues the claims you plan to map, and whether those values are stable for each user over time.",
LDAP lets Superset check passwords against your existing directory and map directory groups to Superset roles through AUTH_ROLES_MAPPING. This is common where the directory is the system of record for staff access and where the security team already manages group membership there. Account creation, password policy and removal of leavers stay in the directory, which keeps access reviews in one place.
- Directory structure: Confirm the search base, user filter and group attributes your directory uses. These vary between Active Directory and other LDAP servers.
- Role mapping: Use AUTH_ROLES_MAPPING to connect each directory group to a Superset role. Keep the mapping table short and documented, because every group you map becomes a permission you must review.
- Service account: Superset needs a bind account to search the directory. Ask who issues it, how its password rotates and what read scope it has.
- Connectivity: Superset must reach the directory from its network segment, often across firewalls. Confirm TLS for the connection before go-live.
Before cutover, confirm with your directory team which groups represent analytics access and whether nested group membership needs to be honored.",
Database login stores Superset user accounts in its own metadata database, with passwords managed inside Superset. It is the simplest option to set up and needs no external identity system. For small or isolated teams, or for deployments that must run without a network path to an identity provider, it can be a reasonable choice. The trade-off is that every account, password and removal is a manual task within Superset.
- Account lifecycle: Someone must create, disable and remove accounts in Superset when staff change roles. Assign that task to a named owner.
- Password policy: Database login inherits no policy from your organization. Confirm how passwords are set and reset and how they are protected in transit.
- Access reviews: Reviews must be performed inside Superset, separate from your central identity records, so define a recurring export or report for auditors.
- Future move: Moving later to an external provider means remapping accounts, so decide now whether this is a temporary or long-term choice.
Before choosing this path, confirm with your security team that local accounts meet your password and review requirements.
What to prepare before changing the login method
Changing the login method touches the metadata database, the secret key, the role model and the identity provider at the same time. The cards below cover what to capture and protect before the first change, so a failed login test can be rolled back without losing users or sessions.
Back up the metadata database
Superset keeps users, roles, dashboards and saved configuration in its metadata database, so a verified backup is the rollback point for the whole switch. Superset supports PostgreSQL 10 to 17 and MySQL 5.7 and 8.x for this database, and the backup should be taken from the version you run in production. Confirm you can restore it to a separate host and that someone other than the operator has checked the restore. Take a fresh backup immediately before running superset db upgrade.
Protect SECRET_KEY and PREVIOUS_SECRET_KEY
Superset requires a user-specified SECRET_KEY to start, and changing it without a plan invalidates sessions and encrypted values stored in the metadata database. Keep the current key in your secrets store and record where it is injected into the deployment. If the key must rotate during the work, set PREVIOUS_SECRET_KEY to the old value so existing data can still be read. Check that the key is not hard coded in a configuration file that the change will overwrite.
Inventory AUTH_OID and role mapping
List every place AUTH_OID appears in your superset_config.py and any mounted override files, along with AUTH_USER_REGISTRATION, AUTH_USER_REGISTRATION_ROLE and any AUTH_ROLES_MAPPING entries. Record which roles are granted through OpenID claims today and which are assigned by hand. This inventory tells you which groups must exist in the new provider and which users will lose a role if the mapping is not rebuilt.
Build a staging copy of production
Restore the production metadata database into a staging environment with the same Superset version, Python packages, caching layer and worker configuration. Staging should use the same reverse proxy and hostname pattern so that login redirects behave as they will in production. Without this match, a login test can pass in staging and still fail after cutover. Plan staging for the full sequence, including the upgrade to 6.0 and the new authentication settings.
Register the identity provider application
The OAuth or OpenID Connect application must be created in the identity provider by the client's identity team, with redirect URLs that match the Superset host name in each environment. Agree on who owns the client ID and secret, how they are rotated and where they are stored. Request the group or claim names that Superset will use for role mapping before the build begins. Staging and production should use separate registrations so that test logins do not reach production records.
Plan user matching before the switch
Superset links a login to an existing user record, usually by username or email, so a mismatch can create a second account and orphan ownership of dashboards and charts. Export the current user table, compare it with the identifiers the new provider will send, and decide how duplicates, renamed people and departed staff are handled. Agree the rule with dashboard owners before cutover so that ownership is not reassigned by accident.
Keeping user records matched during the switch
Superset stores every user in its metadata database, and ownership of dashboards, charts, saved queries and role assignments all point back to that user row. The new login has to produce the same username or email key as the old one, or the team has to plan a reconciliation that moves ownership and roles onto the right records. Before changing the authentication type, export the current user list from the metadata database and record which attribute each account was created from. Confirm which claim your identity provider returns for the username or email, and confirm how Flask-AppBuilder in your Superset version maps that claim to the user record. Do not assume the mapping matches what the old OpenID login produced, because OpenID 2.0 identifiers and OAuth or OIDC subject values are often different.
Next, check for duplicate accounts before go-live. A common case is one person who has an older local account and a new account created by the first federated login, with different casing or a different domain in the email field. Duplicates split dashboard ownership and make role assignments look inconsistent in the Superset user list. Decide in advance whether to merge, deactivate or keep each duplicate, and who signs off on that decision. Then compare the metadata database users against the current directory and deactivate accounts for people who have left or no longer need access. Deactivating is safer than deleting, because deleting a user can break ownership references on existing content.
Finally, test role assignment on a sample of users from each group that maps to a Superset role through AUTH_ROLES_MAPPING. Include administrators, a data analyst who owns dashboards, and a viewer with restricted datasets. Log in through the new provider in a staging copy of the metadata database, then confirm each user gets the expected roles and can still open the content they own. Record the results so the sign-off covers both login and authorization. Exact behavior depends on your identity provider and Flask-AppBuilder version, so confirm those details against the Flask-AppBuilder security documentation and your own test environment before relying on them.
What makes this migration take longer or shorter
This table compares the factors that expand or shrink the AUTH_OID to OAuth work, and the direction each one pushes the effort. Read each row as a question to answer during scoping, because most of these factors are only known once your identity inventory and database size are measured.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Identity providers or directories in use | Each provider needs its own redirect configuration, group mapping and test login, so more sources add work in parallel. | Consolidate to one identity provider for Superset where your identity team agrees, and retire unused sign-in paths. |
| Users and roles to match | Matching existing AUTH_OID user records to new identities takes longer as the user count and role variety grow. | Export current users and roles before design starts and agree on a single matching key such as a verified email. |
| Custom security manager code | Overrides of the Flask-AppBuilder security manager must be reviewed against the new authentication type, which adds review and test cycles. | Keep custom security code minimal and document each override so it can be re-tested against the new login method. |
| Group mapping complexity | Mapping many groups to Superset roles through AUTH_ROLES_MAPPING requires agreement from identity owners and tests for each group. | Limit mappings to the roles that carry access decisions and let the identity provider own group membership. |
| Metadata database size and downtime window | A larger metadata database takes longer to back up and migrate, and a short approved window leaves less room for retries. | Measure database size in staging, rehearse the upgrade there and schedule a window with a rollback point. |
| Access to identity provider admins | Redirect URIs, client secrets and claims rules sit with other teams, so waiting on their change tickets can stall the work. | Name the identity owner and their approver before the project starts and request client registrations early. |
| Upgrade and login change in one phase or two | Doing both together means one cutover with more moving parts to test, while separate phases add a stable interim state to run and verify. | Decide the phase plan early, keeping the login change on the existing version first if the user base is large. |
Questions teams ask before moving off AUTH_OID
How much does moving off AUTH_OID cost?
No fixed price applies to every deployment. Cost follows from the written scope, and DeployOpen does not publish a price list. The main drivers are the number of identity sources (OAuth or OpenID Connect, LDAP, database login), how many groups must map to Superset roles through AUTH_ROLES_MAPPING, the state of your metadata database, and whether you need a staging environment built or reused. The migration build and testing are one-time work. Ongoing identity configuration changes, upgrades and any support arrangement recur. Ask for a quote with separate lines for design, configuration, staging tests, cutover support and handover, so you can see which parts your team could take on.
How long does an AUTH_OID to OAuth switch take?
No duration applies to every environment, so the timeline should come from your scope rather than a generic figure. Superset 6.0.0 was published on December 18, 2025, and deployments still on AUTH_OID need to move before they upgrade past the point where the type is removed. The schedule is set by the number of identity sources, the readiness of your identity provider registration, how many dashboards and roles need checking in staging, and how many change windows your team can use. Ask for milestones with dependencies, including who approves each cutover.
What must our team provide for the switch?
The switch depends on access and decisions from your side. Plan to provide:
- Administrator access to the identity provider or directory, including the ability to register an OAuth client and set redirect URIs
- Named contacts who own the identity provider, the directory and the Superset platform
- A staging Superset built from the same release and configuration as production, with a recent copy of the metadata database
- A test user set covering each role, group and login method in use
- Agreement on the login attribute that matches an existing Superset user
- A change window and a rollback decision owner
Without staging and a test user set, the team cannot confirm dashboard ownership or role mapping before cutover.
Can our own team move off AUTH_OID alone?
Yes, if your team has the skills and access the work needs. The task involves editing Superset configuration in Python, setting up an OAuth or OpenID Connect client, or configuring LDAP, and mapping groups to roles. It also needs a tested metadata database backup, a staging run of superset db upgrade and superset init, and a check of UPDATING.md for other breaking changes in the same release. Teams without an identity specialist or with no staging environment often use a partner for design and testing. Compare the skills you hold with the list above before deciding.
Can we keep OpenID 2.0 running after Superset 6.0?
No. Superset 6.0 upgraded Flask-AppBuilder to 5.0.0, which removed the AUTH_OID authentication type, so an upgraded deployment cannot keep using it. Flask-AppBuilder documents that OpenID 2.0 support was removed and that OpenID Connect should be configured through OAuth providers. Keep the old login working only on the current release until you cut over in staging and production. Your replacement options are OAuth providers (including OpenID Connect), LDAP, or database login. Confirm the chosen method works in staging before the upgrade.
Will users lose dashboards or roles during the switch?
Dashboards and charts live in the metadata database, so they should remain when the login method changes, provided each returning user matches an existing user record. Roles for OAuth or LDAP users come from group mappings in AUTH_ROLES_MAPPING, so a missing or renamed group can leave someone with fewer permissions. The main risk is an attribute mismatch, such as a changed username or email claim, which can create a separate user and leave the old owner of a dashboard unreachable. Confirm in staging how each login path matches existing users, and check ownership and roles for a representative set of accounts before cutover.
What does the AUTH_OID migration not cover?
The login migration does not include the other changes in a major upgrade. Plan separately for:
- Custom visualization plugins, theme changes and Docker image changes that affect your build
- SQL functions that the new release disallows and queries that depend on them
- Changes to dashboards, reports and alerts that the release notes list
- Identity provider policy design, such as password rules, session lifetime and multi-factor requirements
- Compliance evidence and audit reports, which independent auditors issue
Ask for these items explicitly in the scope so nothing is assumed to be included.
Does the switch mean we pass our compliance audit?
No. Moving login to a supported method helps your access control evidence, but passing an audit depends on how the whole environment is operated and documented. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make that determination. Ask your auditor which access and logging records they will test, and confirm that your scope includes producing those records from the new login setup.
What stays with your team after the switch
The login cutover does not end the work. Once users sign in through an OAuth or OpenID Connect provider, your team owns the identity configuration in Superset: the AUTH_TYPE setting, the provider entry in OAUTH_PROVIDERS, and the AUTH_ROLES_MAPPING table that turns provider groups into Superset roles. Someone needs to watch for changes on the identity provider side, such as a renamed group, a changed claim, a rotated signing key or a retired application registration. Each of these can lock users out or quietly hand them the wrong role. Name an owner for the Superset client registration, and agree how identity provider changes reach that owner before they are made, not after users report failures.
Client secrets and role mappings also need a routine. Rotate the OAuth client secret on a schedule your identity team sets, and test the rotation in staging first, because a secret change without a matching update in Superset breaks every login at once. Review AUTH_ROLES_MAPPING whenever the group structure changes, and check that removed or reorganized groups do not leave former staff with access they should have lost. Keep the record of who approved each mapping, since auditors who test access controls will ask for it. DeployOpen does not issue audit reports or certifications. Independent auditors decide whether your access controls meet the criteria they test, and the evidence you keep here is what they will examine.
Track the project's UPDATING.md notes for every release, not only major ones. Authentication behavior can change again through Flask-AppBuilder upgrades, and the breaking change notes are where removals like AUTH_OID appear first. Assign someone to read the notes before each Superset upgrade and to confirm that login still works in staging with a test user from each role. Confirm with your identity provider vendor which OpenID Connect features and token lifetimes they support, since those settings sit outside Superset and affect session behavior.
How DeployOpen scopes and delivers an authentication migration
DeployOpen plans the move from AUTH_OID to OAuth as a fixed-scope piece of work agreed in writing before any change is made to your Superset deployment. The engagement covers the identity provider choice, the user record matching plan, the build in your own infrastructure, and a handover your team can run after the switch.
How we scope
- Inventory every Superset login path that uses AUTH_OID and every user who signs in through it today.
- Agree which target authentication type applies to each user group, such as OAuth, LDAP or database login.
- Confirm the Superset version, Flask-AppBuilder version and metadata database versions in the written scope.
How we build
- Configure the chosen provider in a staging copy of your Superset deployment before touching production.
- Test the matching of existing user records by username and email, and record every mismatch for review.
- Map provider groups to Superset roles with AUTH_ROLES_MAPPING and test each role against real dashboard access.
How we hand over
- Deliver the configuration, the role mapping table and the user matching report as written documentation.
- Provide a cutover runbook covering the metadata database backup, superset db upgrade and superset init steps.
- Walk your operations team through the rollback steps and the test results before the engagement closes.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after the migration is complete.
- Review provider and role changes as part of any retainer, so access stays aligned with your access model.
- Ask your identity team to confirm the provider's current OAuth or OpenID Connect requirements before the scope is signed.
