Why automate Superset user and role management with the API
Automating user and role management with the API lets a team create, update, deactivate and assign roles to Superset accounts from a script or pipeline instead of clicking through the Security menu. The payoff is that joiners and leavers follow the system of record, such as HR or an identity provider, rather than a ticket queue, and that every change runs through the same reviewed code path. This matters most when the estate has grown past a handful of administrators, when dashboards expose sensitive data to changing teams, or when an auditor asks you to show who held which role on a given date. Manual administration tends to fail quietly: a leaver keeps an active account for weeks, and an access review becomes a screenshot exercise that nobody can repeat.
Superset is built on Flask-AppBuilder, and its security management endpoints are exposed through the FAB security API. That API is off by default. Before you design any sync job, confirm in your own build that FAB_ADD_SECURITY_API is enabled in the configuration, and plan to restrict who can reach it, since anyone holding an API token that can call these endpoints can change access. The Superset configuration documentation is the place to confirm how the flag and related authentication settings behave in the version you run.
Version changes matter here. In Superset 6.0.0 the List Roles view moved to the frontend, and the release notes state that FAB_ADD_SECURITY_API must be enabled and superset init run for it to work. Teams that script against role listings on older releases should test those calls again after upgrading, and should check the UPDATING notes for the version they are moving to before they change any sync logic. Treat the API as a supported control only after you have tested it in staging against the exact version in production.
Which provisioning path fits your identity setup
This table compares four ways to get users and roles into Superset: manual administration, API scripts driven by an HR export, SSO with role mapping at login, and a scheduled reconciliation job. Read each row against your identity source and who will own the job when it fails. Most regulated teams end up combining SSO for sign-in with a reconciliation check for accounts and roles that never pass through login.
| Option | When it fits | Who maintains it | Main trade-off |
|---|---|---|---|
| Manual administration in the UI | Small user base, few role changes, and no central HR or IdP system feeding access | Superset admins, by hand | Simple to start, but offboarding depends on someone remembering to act and leaves no automatic evidence trail |
| API scripts driven by an HR export | HR is the source of truth but Superset login is not federated, or some accounts must exist outside SSO | Your platform or identity team, as custom code | Full control over create, update and disable calls, but you own the script, its credentials and every change to the export format |
| SSO with AUTH_ROLES_MAPPING at login | Your IdP already holds group membership and you want roles assigned when users sign in | Identity team for groups, Superset team for the role mapping config | Roles follow group membership at login, but users who never sign in keep existing accounts, so you still need a cleanup path |
| Scheduled reconciliation job | You run SSO or an HR export and need to catch drift, orphaned accounts and roles that no longer match policy | Platform team, with a named owner for the report | Catches gaps the other paths miss, but only detects problems on its schedule and needs a clear rule for who approves removals |
How to set up API-driven provisioning in order
This sequence moves API-driven user and role provisioning from a design on paper to a logged production process. Each step ends with a check you can record, so the team knows the release, the data and the service account are ready before any change reaches real users.
Confirm the release and its breaking changes
Identify the exact Superset version your environment runs and the version you intend to target. Read the UPDATING.md notes for every version between them, because the role-listing behavior changed in 6.0.0 and provisioning scripts that depend on it will need changes. Record which notes affect user, role or security API behavior. Done means you have a written list of the notes that touch your scripts, reviewed by the person who owns the integration. Confirm the target version with your own support plan, since the release list changes over time.
Back up the metadata database
Take a full backup of the metadata database before changing anything, because user, role and permission rows live there and a bad script run can change many of them at once. The backup owner is the platform team, working with the database administrator. Store the backup outside the Superset host and record the time, the database version and the secret key reference used for encrypted fields. Done means a restore test has been scheduled or completed on a separate instance, so you know the backup is usable and not just present.
Enable the FAB security API in staging
In a staging instance that matches production configuration as closely as you can manage, set FAB_ADD_SECURITY_API to enabled in the Superset configuration. Without this flag the security endpoints used for user and role management are not exposed. Restart the web tier so the setting takes effect. Done means an authenticated request to the security API returns a response from the instance, and the response confirms that the flag is active. Keep a copy of the configuration change in version control so production receives the same change.
Run superset init in staging
Run superset init against the staging metadata database after the upgrade or configuration change, so the default roles and permissions are created or updated to match the release. The platform engineer runs the command from the same image or environment used by the web tier. Review the output for errors on permission sync. Done means the command completes without error and a list of roles through the API matches what the admin interface shows for the same instance.
Create a least-privilege service account
Create a dedicated Superset user for the provisioning integration and assign it only the roles needed to manage users and read roles, not Admin. Give it a name that identifies it as automation, store its credentials in your secrets manager and set a rotation owner. Restrict its login path so it is not used for interactive sessions, using whatever method your identity setup supports. Done means a test call that creates a sample user succeeds, and a test call that attempts an action outside the granted roles is refused.
Map source-system roles to Superset roles
Write down which HR or identity provider groups correspond to which Superset roles, and which attributes drive account creation, role changes and deactivation. Ask the data owners to approve the mapping, and include a default role for new accounts that grants no data access. Keep the mapping in a file under version control so reviewers can compare it with later changes. Done means every source group has either a target role or an explicit decision to exclude it, and the owner has signed off on that document.
Test create, change and deactivate flows in staging
Run the sync against staging with a set of test identities that cover a new hire, a role change, a leaver and an edge case such as a user who appears in two groups. Check that each change produces the expected user and role state in Superset, and that deactivated accounts can no longer sign in while their history remains in place. Confirm that the sync is idempotent by running it twice and checking that no duplicate users or extra role grants appear. Done means every test case has a recorded result, and any failure has a fix and a retest.
Roll out to production with logging
Apply the reviewed configuration, the service account and the sync job to production in a planned change window agreed with the business owner. Turn on logging for every provisioning action, including the actor, target, role change and result, and send it to the log store you use for audit review. Run the first sync in a dry-run or limited scope if the script supports it, and compare the results with the expected list before enabling the full schedule. Done means the first production run matches the reviewed expectations and the log entries can be found by the audit team.
Security risks in automated account changes
Automating user and role changes moves access decisions out of individual admin clicks and into a service account, a script and a data feed. The cards below cover the controls you must own so that a provisioning job cannot quietly grant more access than your access model allows.
Over-privileged service accounts
The account that calls the Superset REST API can create users and assign roles, so it is effectively an administrator. Give it only the role-management permissions your provisioning job needs, and keep it out of the Admin role used by people. Ask who can log in as this account, whether it has a password login at all, and whether its permissions are reviewed on a set schedule. A compromised automation account with broad rights is one of the fastest routes to full control of dashboards and database connections.
API flag enabled without review
Superset 6.0.0 requires FAB_ADD_SECURITY_API to be enabled before the role and user endpoints work, and it requires superset init to be run. Turning this on in production exposes management endpoints that were not reachable before, so the change should go through the same review as other configuration changes. Record who approved it, which environment it was tested in first, and confirm that it is set in the deployed configuration rather than only in a test file.
Orphaned accounts after deprovisioning
A deprovisioning job that disables a user in the source system but misses the Superset side leaves an active login and possibly live sessions. Confirm that deactivation sets the Superset user to inactive, that the job removes role assignments, and that it handles users whose source record is deleted rather than marked leaving. Check that a removed user cannot still reach dashboards through public links, embedded sessions or saved owner settings.
Role drift from HR data
Roles in Superset can drift from the HR or identity source when someone changes department but keeps an old role, or when a manual change made in the UI is overwritten or left in place by the next sync. Decide which system is the source of truth for each role, and whether the sync adds roles only, replaces them or reports differences. Run a comparison report on a schedule so that unexpected grants are seen by a person before they become a standing exception.
Secrets for the service account
The provisioning job needs credentials to call the API, and those credentials often end up in CI variables, cron files or container environment settings. Store the token or password in a dedicated secrets manager, rotate it on a defined schedule, and scope it to the one Superset environment it serves. Confirm that logs from the job do not print request headers or payloads that contain the credential.
Provisioning logs and evidence
Every account and role change made by the job should be traceable to a source record, a run and a person who approved the rule. Keep the job's input files, its change list and its result in a log store that the automation account cannot edit. Ask whether your audit trail in Superset records API-driven changes with the same detail as UI changes, and test that a sample change can be traced from the HR record to the Superset role in a single review.
Questions teams ask before automating Superset access
What work is involved in automating Superset user and role management?
Automating access means building a controlled process that creates, updates, and removes Superset users and roles through the REST API, driven by an authoritative source such as HR or an identity provider. The work covers mapping source attributes to Superset roles, writing and testing the sync job, deciding how deprovisioning works, setting up logging of every change, and running the job against a staging instance before production. Superset 6.0.0 moved the List Roles view to the frontend and requires FAB_ADD_SECURITY_API to be enabled and superset init to be run, so the security API must be turned on deliberately and verified after upgrades. The team that owns the Superset instance, the team that owns the identity source, and whoever signs off on access policy each have a part in the work.
How long does it take, and what changes the timeline?
The timeline depends mainly on how many source systems feed the process, how many roles and role mappings must be agreed, and how many exceptions exist, such as contractors, service accounts, or users who hold roles across several databases. A single authoritative source with a small, stable role set is much less work than several sources that disagree about who is an employee. Each source needs a field mapping, an agreed rule for what counts as a leaver, and a test plan. Ask for a timeline in the written scope that lists these inputs, because a fixed-scope quote can only be firm once the sources and roles are known.
Can our own team build this in-house?
Yes, a team with Python or scripting experience, access to a staging Superset, and a working knowledge of the Superset security model can build a sync job in-house. The harder parts are usually not the API calls. They are agreeing on role design, handling edge cases such as rehires and duplicate usernames, proving that removals took effect, and keeping the job working through Superset upgrades. Check the upgrade notes for each release before updating the job. Many teams keep the design and ownership internal and bring in an outside partner for a fixed-scope build, a review, or a test pass, depending on where their skills are thinnest.
What do our HR and identity owners need to provide?
HR and identity owners need to define the authoritative fields for each person, including a stable unique identifier, employment status, department or team, manager, and start and end dates. They must also confirm when a leaver record is created, how quickly changes are published, and who can correct a wrong record. On the Superset side, owners must agree which roles map to which groups, who approves exceptions, and whether contractors receive accounts. Without these decisions, the sync job will either create accounts that should not exist or leave access in place after someone leaves. Ask the engagement to produce a short written mapping document that both teams sign off.
How do we verify that deprovisioning actually worked?
Verify deprovisioning with evidence, not with the job's exit code. Compare the set of active Superset users against the authoritative source on a schedule, and report any active account whose source record shows a leaver or no record at all. Confirm that the account is deactivated and that its roles are removed, and check that existing sessions stop working. Keep the action log entries for each change so that an auditor can trace who was removed, when, and by which job run. Test this path in staging with a test leaver before production, and include a failure alert so that a broken sync does not fail silently.
Does the API replace single sign-on?
No. The API manages accounts and roles inside Superset, while single sign-on decides how people authenticate to Superset. Flask-AppBuilder supports OAuth2 providers and LDAP, and AUTH_ROLES_MAPPING can map groups from those sources to Superset roles. Many teams use SSO for login and group-based role mapping for most access, and reserve the API for cases the mapping cannot express, such as bulk corrections or audit reports. If you use both, decide which system is the source of truth for each attribute so the two do not overwrite each other. The SSO and authentication work is covered on its own page.
What drives the cost of this work?
Cost follows the amount of design and verification, not the code volume. The main drivers are the number of source systems, the number of roles and exceptions, the quality of the source data, the number of environments that must be tested, and how much logging and reporting the audit team requires. Recurring costs include keeping the job aligned with Superset releases and reviewing role mappings when the organization changes. When requesting a quote, ask for the source list, the role matrix, the test plan, the handover documents, and what happens after go-live. DeployOpen does not publish prices, and a quote follows from the written scope.
What to confirm in your Superset release and environment
The API surface for user and role management changes with the Superset release you run and with the environment around it. The cards below are questions to settle with your vendor documentation and your own test instance before you write provisioning code.
Exact endpoints and payloads for your version
Confirm which user and role endpoints your release exposes, which fields each one accepts, and which values it requires for role assignment. Ask whether the role list and role detail views are served by the backend or the frontend in your version. Record the request and response shapes from a staging instance running the same release, and keep them in the repository next to your sync code so a version change shows up as a diff.
Behavior of the API flag after upgrades
Confirm that FAB_ADD_SECURITY_API is still enabled after each upgrade and that superset init has run before you test the endpoints. Check whether your upgrade process resets or overrides the setting in your configuration file. A sync job that worked before an upgrade can fail silently if the security API is no longer exposed, so add a health check that calls the endpoint before each run.
The 7.0.0 pre-release status
Confirm whether your planned release is a stable version or a pre-release. The release page lists 7.0.0rc2 as a pre-release, so do not design provisioning logic around its API until the stable release notes confirm the endpoints. Ask your team which version your production instance will run for the next planning cycle, and document the upgrade path from it.
Handling of users who log in through SSO
Confirm how users created by your SSO or LDAP login path are stored and whether the API can update their role assignments without conflicting with group mapping. If AUTH_ROLES_MAPPING assigns roles at each login, an API change may be overwritten the next time the user signs in. Decide which system owns each role, and test a user who is deprovisioned in the directory but still holds an active session.
Audit events beyond the built-in log
Confirm whether the built-in action log records every user and role change your auditors expect, including who made the change through the API and from which client. Ask your compliance lead which evidence must be retained, for how long, and where. If the built-in records are not enough, plan a custom event logger or a forwarding step to your SIEM before the first production sync runs.
Service account permissions and secret handling
Confirm which role the service account that calls the API needs, and whether it can grant roles above its own level. Confirm where its credentials are stored, how they rotate, and whether the account is excluded from interactive login. Limit it to the user and role actions the sync requires, and review its activity alongside the audit records.
Pairing API provisioning with SSO and group mapping
Use SSO for authentication and the API for account lifecycle and role assignment. The identity provider answers whether a person is who they claim to be, and Superset decides what that person can do. When a user signs in through OAuth2, LDAP or another configured provider, Superset builds the account from the claims it receives, and AUTH_ROLES_MAPPING can translate group membership into Superset roles at login. The REST API is the lever for everything the login flow does not reliably cover: creating or disabling accounts ahead of first sign-in, assigning custom roles, and removing access when a person leaves. Decide this split before you write any automation, because two systems writing roles to the same user will produce changes that nobody can explain later.
Confirm three things in your own environment before relying on the mapping. First, check how your provider sends groups (as a claim, in a token, or through a directory lookup) and whether the group names match the role names in AUTH_ROLES_MAPPING exactly. Second, check whether a role that the API grants persists after the next login, or whether the login mapping rewrites the user's roles each time. The behavior depends on your Superset version and authentication configuration, so test it with a disposable account in staging rather than assuming it. Third, check which roles the mapping is allowed to touch. A mapping that replaces all roles on each sign-in will silently remove anything the API added. Record the answers, because they decide which system is the source of truth for each role.
When both sources apply, the safe default is that the most restrictive decision wins on access, and that the system of record for each role is explicit. In practice, keep group-derived roles for broad job-function access that your identity team already governs, and reserve API-managed roles for exceptions and row-level or dataset-specific grants that no group carries. Deprovisioning should disable the account through the API and revoke the identity provider session, not depend on the user never signing in again. Write a small test plan that signs in as a user with conflicting sources, changes one group, and checks the resulting roles in the Superset user list. Keep those results with your change records, since auditors will ask how a role got onto an account.
How to audit provisioning changes over time
Security and compliance reviewers need to answer a narrow set of questions: who was granted or removed a role, who approved it, when the change took effect, and which system made it. Superset's own change history is not enough for that, because the records sit in the same database that the provisioning job writes to, and they can be altered or lost during a restore. Plan the audit trail as a separate artifact that your team owns and retains under your own policy.
- Source-of-truth change record: Store each provisioning request, its approver reference and the timestamp in your ticketing or IAM system, and link it to the API call that carried it out.
- Actor identity: Use a dedicated service account for the provisioning job so every change is attributable to the automation, and record the human who triggered or approved it.
- Retention: Confirm with your compliance lead how long provisioning evidence must be kept and where it is stored, and apply the same retention to exports.
- Access review evidence: Export the user and role assignments on a fixed schedule and keep each snapshot with its date.
- Exception handling: Require a documented reason for any manual change made through the interface, and reconcile it into the trail.
Before relying on the trail, ask your auditor which control evidence they expect for account lifecycle and role assignment, and confirm the format they accept.
Platform engineers care about whether the provisioning job ran, what it changed, and what failed. A silent failure is the main risk: an offboarding call that returns an error and is never retried can leave an account active. Treat the job like any other production integration, with structured logs, retries with backoff, idempotent operations and alerts on failure.
- Structured job logs: Log each create, update, role change and deactivation with the target username, the requested change, the response status and a correlation ID.
- Retries and idempotency: Make each operation safe to repeat, so a retry after a timeout does not create duplicates or fail on an existing role.
- Failure alerts: Page or notify on failed deprovisioning calls first, since they carry the most risk, and on jobs that do not complete within the expected window.
- Dead-letter queue: Hold failed operations for manual review rather than dropping them after the final retry.
- Run history: Keep job runs for a period your team agrees on, so you can reconstruct the state at any past date.
As a check, deliberately fail a deprovisioning call in staging and confirm that it is retried, alerted and visible in the dead-letter queue.
Logs show what the job attempted, but they do not show whether Superset still matches the authoritative record. Reconciliation compares the active users and role assignments in Superset against the HR or identity source on a schedule and reports any drift. This catches changes made outside the job, missed events and accounts that were never linked to a person.
- Scheduled export comparison: Pull the user list and role assignments through the API, normalize them, and diff them against the HR or directory extract for the same date.
- Drift categories: Separate accounts with no matching person, people with extra roles, and terminated people who still hold active accounts, since each needs a different response.
- Owner assignment: Route each drift item to a named owner with a due date, and record the resolution in the audit trail.
- Extract timing: Compare against an HR extract taken at the same point in time, or differences caused by late updates will look like access problems.
- Manual changes: Flag any account created or edited outside the provisioning identity, using the audit log in Superset where it is enabled.
Confirm the field mapping for matching accounts, such as employee ID or email, before the first reconciliation run, because a mismatched key produces false drift.
A deprovisioned user who can still sign in is the failure auditors and security teams most want to rule out. Tests should prove the outcome from the user's side, not only that the API returned success. Sign-in can be blocked at several points: the account being inactive, the role being removed, a cached session still being valid, or an identity provider still issuing tokens. Each path needs its own check.
- Positive and negative test accounts: Use test accounts that are deactivated in the same way production offboarding works, then attempt login through every enabled path, including SSO and any local login.
- Session behavior: Confirm that an existing browser session ends or fails on its next request, and document the session lifetime you configure.
- Identity provider check: Verify that the upstream account is disabled, because a Superset deactivation does not stop the identity provider from issuing tokens.
- API token check: Confirm that any API credentials tied to the user no longer authenticate.
- Repeat on change: Re-run the test after each Superset upgrade or authentication configuration change, and keep the results with the audit evidence.
Ask your identity team which session and token lifetimes apply to your setup, and record them with the test results.
How DeployOpen scopes and delivers Superset provisioning
DeployOpen plans user and role provisioning for Superset inside your own infrastructure, on your cloud accounts, data center or restricted network, and agrees a fixed written scope before any work starts. The scope names the systems that feed identities into Superset, the roles each source may assign, the directory groups that map to Superset roles, the audit destination for change events, and the deprovisioning rules you approve. A quote follows from that written scope, so you can compare it directly against the cost of doing the same work with your own team.
The service account that calls the REST API is the highest-risk part of this design, so it receives specific attention. DeployOpen works with your security team to define a dedicated account with only the permissions the sync needs, store its credentials in your secrets system, restrict where it can connect from, and rotate its credentials on a schedule you set. Because the Flask-AppBuilder security API is an explicit switch that must be enabled, the scope also records who approves that change and how it is tested. Confirm with your Superset version's release notes which security API endpoints your deployment exposes before the design is signed off.
DeployOpen documents each flow as part of delivery: the create, update, role change and deprovision paths, the failure and retry behavior, the reconciliation job, and the runbook for an operator who must disable an account by hand. You receive the documentation and the code or configuration in your own repositories. DeployOpen is a Chainscore Labs company. It prepares controls and evidence that your auditors can test, but it does not issue audit reports, attestations or certifications, and independent assessors make those determinations. If you want continued help after handover, ongoing support, upgrades and testing of the provisioning flows are available as a retainer under a separate written agreement.
