Which Apache Superset built-in role should each user get?
Many new Superset rollouts start with a shortcut: the first administrator creates accounts, and everyone who needs to build a chart gets Alpha, or the person who asks for "full access" gets Admin. That works for a pilot, but it makes the role decision for every later user before anyone has checked what each built-in role can change. The built-in roles are Admin, Alpha, Gamma, sql_lab and Public. Admin manages the whole instance, including users, roles and database connections. Alpha can edit content it does not own and sees more objects than Gamma. Gamma is the read-oriented role for consumers of dashboards, and sql_lab adds access to SQL Lab, which is where ad hoc SQL is written. Public covers anonymous access, which should stay off unless you have decided otherwise.
Map roles to populations before you assign them. Start with a short list: platform administrators, dashboard builders, analysts who write SQL, and viewers. Usually only the first group needs Admin, and builders need Alpha only when they must edit dashboards and datasets owned by other people. Most viewers need Gamma, and analysts who write SQL usually need Gamma plus sql_lab, scoped by the data access rules in the sibling pages on custom roles and SQL execution. Ask each group's manager which objects they must change, not which objects they might like to change. Record the decision in your access register so an auditor can trace each grant to a business need.
Edits to built-in roles are fragile. Superset's upgrade guidance says to run superset init after superset db upgrade, and that command resets the permissions of the built-in roles to their defaults. If you have edited Gamma or Alpha in the UI, those changes can be lost during an upgrade. Confirm this behavior against the version you run, using the Superset upgrade documentation, and keep any custom access in separate custom roles. Test your role map in staging after every upgrade by logging in as one test account per role.
Built-in roles and when each one fits
This table compares the five built-in Superset roles by what they let a user do: edit content, connect data sources, run SQL Lab, see dashboards and manage users. Read each column as a default that you must confirm against your Superset version, then match the role to the population it suits. The main takeaway is that Admin and Alpha are granted far more than most users need.
| Role | What it allows (qualitative) | Population it suits | Main risk if over-assigned |
|---|---|---|---|
| Admin | Full control of the instance, including user management, roles, databases and all content | A small number of platform owners who administer Superset itself | Any compromise or mistake reaches every database, dashboard and user |
| Alpha | Broad content editing and data source connections, with access wider than Gamma but narrower than Admin | Analysts or data engineers who build datasets and charts across several sources | Can create or alter connections and content that other users depend on |
| Gamma | Viewing and working with dashboards and datasets granted to the user, with limited editing rights | Most business users who consume dashboards and explore approved data | Easy to under-scope, so users may see nothing until dataset or dashboard access is added |
| sql_lab | SQL Lab access to run ad hoc queries, granted in addition to another role | Users who need ad hoc SQL against approved databases only | Ad hoc SQL can read any table the database account exposes, so pair it with database-level limits |
| Public | Anonymous or unauthenticated visitor access, only where explicitly enabled | Rarely appropriate for internal rollouts; sometimes used for published dashboards | Exposes any content granted to the Public role to anyone who can reach the URL |
| Confirm before rollout | Exact permission sets differ by version, so check the role and permission lists in the documentation for your release | Use the output of your own role listing as the baseline for review | Assumptions from older versions can grant more or less than you expect |
Why Admin and Alpha are over-assigned in most rollouts
Admin and Alpha are over-assigned because teams optimize for the first week after launch and stop there. During rollout, a user who hits a permission error on a chart, dataset or dashboard usually gets the fastest fix by being moved up a role, and nobody is tasked with reversing that change later. Alpha is the most common casualty. Teams often treat it as a sensible middle tier between Gamma and Admin without checking what it actually reaches. In Superset, Alpha can create and edit content across datasets and charts that other people depend on, so a tier chosen for convenience quietly becomes a write-access tier for the whole instance. Before go-live, export the permission set of each role in your own environment and read it against your data classification, rather than assuming the name describes the scope.
The main risk is broad write access to shared objects. A user who can edit a shared dataset can change its SQL, metrics, or the way dashboards built on it behave, which affects people who never touched that user's work. Write access to metadata, including database connections, dashboard ownership and role assignments, widens the blast radius further. If that account is compromised, or simply used carelessly, the attacker or mistake reaches every dashboard and every database connection the account can see, not only the content its owner created. For illustration, a single Alpha account used by an analyst who shares a dataset with the finance team could alter a metric that a board report depends on. Ask who can change datasets and database connections today, and whether each of those people has a documented reason to do so.
Fix this with a recurring review, not a one-time cleanup. Record which population each role was granted for and the reason, and set a date to revisit those grants after go-live and after each upgrade. Confirm with your own tests which permissions your Superset version attaches to each built-in role, because the set of default permissions changes between releases and your assumptions from an earlier version may no longer hold. Reserve Admin for a small number of named platform owners, and move analysts who only need to build charts back to Gamma-based roles with the access they actually use. Expect that some users will push back on losing write access, so agree the escalation path for legitimate needs before you remove the grants.
What Gamma users can and cannot do
Gamma is the built-in role for viewers and light analysts. Within the permissions granted to them, Gamma users can open dashboards, apply filters the author exposed, drill into charts and read the data behind a visualization. Which dashboards appear in their list depends on how you grant access, so confirm this with a test account before you invite a population.
- View assigned dashboards: Gamma users can open dashboards they have been granted access to and use the native filters the author published.
- Explore charts: They can open a chart in Explore and change its settings on data they can already see, and they can save a copy to work on.
- Export results: Exporting data, such as to CSV, is controlled by export permissions, which are separate from viewing. Confirm the export options your version exposes to Gamma.
- Save their own work: Whether a Gamma user can create charts or dashboards in their own space depends on the permissions configured in your build.
Check this by signing in as a test Gamma user and listing every dashboard, chart and export option that user can reach.
Administration of database connections and dataset definitions sits outside the Gamma role. Creating or editing a connection, changing the SQL behind a virtual dataset, and adding metrics or columns are tasks for administrators and, in some cases, for Alpha users. Alpha holds broader data source permissions than Gamma, which is one reason it tends to be over-assigned.
- Database connections: Creating or editing connection details belongs to administrators. Gamma users should never see connection credentials.
- Dataset definitions: Adding datasets and editing their SQL, columns and metrics is outside Gamma's default scope. Test this on your version because permission sets change over time.
- Dataset access is governed separately: Which datasets a Gamma user can query is a grant decision, not a property of the role name. The sibling topic on custom roles for dataset and database access covers how to build those grants.
- Ownership: Dataset owners can affect who edits what. Confirm ownership after any migration or bulk import.
Check this by attempting to create a database connection and to edit a dataset metric as a Gamma test user, then record the result for each version you run.
SQL Lab is the area where Gamma users most often expect more than they should have. Gamma does not include SQL Lab access by default. Access comes from the sql_lab role, and what a user can run then depends on per-database settings, the warehouse account behind each connection, and query limits. The role alone does not define the boundary.
- sql_lab role: Add this role deliberately to the users who need ad hoc SQL, and keep the list short.
- Per-database exposure: A database may be hidden from SQL Lab or restricted, so a role grant alone does not decide which connections a user sees.
- Warehouse account: Unless impersonation is configured for your engine, queries run as the account in the connection. The grants on that account set the real limit on what can be read.
- Row limits and DML: Query row limits and data modification settings apply to SQL Lab queries. Confirm the defaults for your version in the Superset configuration documentation before go-live.
Check this by running a read query and a write statement from a test account that has sql_lab, then confirm the warehouse logs show the account you expect.
Gamma behavior is defined by the Superset version you run, the feature flags you enable and any custom roles you build on top of it. Treat the descriptions in this topic as a starting point and verify them in your environment, because permission sets can change between releases and during upgrades.
- Version differences: Review the breaking change notes in UPDATING.md for each version on your upgrade path, and retest Gamma after every upgrade.
- Edited built-in roles: Running superset init resets edited built-in roles to their defaults, so keep any Gamma changes in a documented, repeatable process rather than in a one-time edit.
- Feature flags: Dashboard-level access controls and related flags change who sees which dashboard. Confirm each flag's effect with a test account.
- Test accounts: Maintain one test account per role population so each upgrade and configuration change can be checked against the same expectations.
Before inviting users, document the Gamma results for your exact version and save them with your access review evidence.
How to map user populations to roles in order
This sequence turns a list of teams into role assignments that give each population the access its work needs and no more. It ends with tested accounts and a written record that an auditor or a future administrator can follow. Run it before the first production user signs in.
Inventory user populations and their tasks
List every group that will sign in to Superset, such as executives who only view dashboards, analysts who build charts, data engineers who query through SQL Lab, and platform administrators. For each group, write down the tasks it performs, the datasets and databases it needs, and whether it must edit anything it did not create. Assign an owner from the business and an owner from IT to approve the list. The step is done when every population has a named owner and a one-line statement of its tasks.
Map each population to the least-privileged role
Start every population at Gamma, the built-in role for users who work with datasets and dashboards they have been granted. Add sql_lab only to populations that must run ad hoc SQL, and confirm in the documentation for your Superset version what that role grants. Reserve Alpha for a small set of users who must edit datasets, and Admin for platform administrators who manage users, databases and settings. Treat Public as a separate decision that applies only if anonymous access is required. The output is a table that maps each population to one primary role and any add-on role.
Assign roles through IdP group mapping
Where your identity provider already holds these populations as groups, map each group to its role with
AUTH_ROLES_MAPPINGin the Superset configuration, so directory membership changes flow into Superset at login. Use manual assignment only for exceptions that no group covers, and record each one with a reason and an approver. Confirm the mapping by signing in with one account from each group and checking the roles on the user record. The step is done when every active account traces to a group or a recorded exception.Remove unjustified Admin and Alpha assignments
Most rollouts start with Admin or Alpha on accounts that were convenient during setup or testing. Compare the current Admin and Alpha holders against the approved list from the first two steps. Downgrade every account without a documented need to Gamma, and remove accounts belonging to people who have left or changed teams. Check whether any default account created at install must be disabled, using your version's production checklist. The step is done when the Admin and Alpha lists match the approved roster exactly.
Test each role with a sample account
Create one test account per role in a staging instance configured the same way as production, then sign in as each one. Check that the Gamma account can open its granted dashboards and charts, but cannot edit datasets, reach the administrative menus, or see databases it was not granted. Check that an account with sql_lab can run queries and one without it cannot. Record the result of each check beside its role. The step is done when every expected allow and deny has a recorded result, and any surprise has returned to step two.
Recheck roles after every superset init
Edited built-in roles are overwritten when
superset initruns, which happens during upgrades and can happen during other maintenance. Keep a change record of every permission you altered on Gamma, Alpha or sql_lab, and store it with your configuration. After each upgrade, rerun the test accounts in staging before production users return. Follow the project's upgrade guide, which calls for a metadata database backup and staging tests first. The step is done when the change record matches the live role permissions after the most recent init.Document the role decision for each population
Write a short record for each population that states its tasks, its primary and add-on roles, its source group or exception, its named owner, and the date of its last test. Keep the records with your access review material so an auditor or a new administrator can trace a user to a role and a reason. Set a review cadence with your security team and repeat the review after every major role change. The step is done when someone outside the rollout team can follow each record from population to role to test result.
How superset init resets edited built-in roles
Running superset init is part of the standard Superset upgrade sequence, and it can reset the permissions attached to built-in roles to the project's defaults. If your team has edited Gamma or Alpha directly in the Superset UI, those edits are at risk of being overwritten the next time the command runs during an upgrade or redeployment. Treat the built-in roles as the project's to manage, and keep every change you need in a role of your own. Confirm the exact behavior for your target version in the Upgrading Superset documentation before you plan the change window, because the reset scope can differ between releases.
Build a custom role on top of Gamma for each access pattern you need, such as a role that can see one schema or one set of datasets, and assign that role to users alongside Gamma. Keep the definition of every custom role in version control, either as a script that calls the Superset CLI or as a documented export that your team can replay on a fresh instance. Record which permissions each custom role holds, who approved them, and the Superset version they were tested against. A role defined this way can be recreated in minutes after a reset, while a role that exists only in the database can be lost or silently changed without a record.
After every upgrade, rebuild or restore, check the state of the built-in and custom roles before you let users back in. Compare the live permissions of Gamma, Alpha and sql_lab with your recorded baseline, confirm that your custom roles still hold their intended grants, and confirm that no user has gained Admin or Alpha access through a reset or a mapping change. Make this check a required step in your upgrade runbook and in the staging test that the upgrade documentation already asks you to run first. Ask your implementation partner or your own platform team to show where the baseline is stored and who reviews the diff.
Security risks in role assignment
Built-in Superset roles are easy to assign and hard to unwind. The risks below share one root cause: a role grants more reach than the user needs, and nothing forces anyone to notice. Each card pairs a risk with the control that keeps it contained.
Default admin account left active
The default admin account created during first setup holds the Admin role, which can change every setting, user and database connection. If the password was never rotated or the account was never disabled, it becomes the easiest path into the whole instance. Before go-live, confirm that the default account is disabled or renamed, that each administrator signs in with a named account, and that admin logins appear in your logs.
Alpha users with broad data reach
Alpha is meant for builders who create charts and datasets, but in most rollouts it is handed to anyone who asks for more access. An Alpha user can see and edit all datasets and dashboards they can reach, which makes it a quiet path to data their job does not need. Map each Alpha grant to a named need, and review the list of Alpha users against the people who actually build content.
Role drift after upgrades
Superset role permissions are stored in the metadata database, and edits to built-in roles can be reset when superset init runs during an upgrade. Teams that customized Gamma or Alpha may find their restrictions gone, or new permissions added without notice. After every upgrade, compare role permissions against a saved baseline before users return to the system.
SQL Lab exposure to Gamma users
The sql_lab permission lets a user run ad hoc SQL against connected databases, and it is often added to Gamma without considering what that user can then query. Gamma users with sql_lab can reach any table their database account allows, bypassing the dashboards and datasets your access model was built around. Grant sql_lab only to named analysts, and pair it with least-privilege warehouse accounts so the database itself enforces the limit.
Group mapping that grants roles too broadly
When LDAP or OAuth groups map to Superset roles through AUTH_ROLES_MAPPING, a broad directory group such as all staff can grant Admin or Alpha to far more people than intended. Mapping errors are silent: users log in successfully with elevated roles and nobody is alerted. Review every mapping line against the group owner, and confirm that privileged roles only come from tightly controlled groups.
No periodic access review
Roles assigned at onboarding tend to outlive the job that justified them, and leavers and transfers keep their access until someone notices. Without a scheduled review, Admin and Alpha assignments accumulate over years. Run a recurring review that lists every user with a privileged role, asks the owner to confirm each one, and removes anything unconfirmed. Keep the review records as evidence for your own governance.
Questions teams ask before changing Superset roles
How much effort does a Superset role review take?
The effort depends mostly on how many distinct user populations you have, how many custom roles already exist, and whether logins come from an identity provider. A review is a bounded piece of work with a clear start and end, so it should be scoped in writing before anyone starts. The main drivers are the number of groups that need different access, the number of users currently holding Admin or Alpha, and whether those users arrived through manual creation or group mapping. A small instance with a handful of roles is a short exercise. A large instance with years of accumulated custom roles, dataset grants and copied permissions takes longer because every grant has to be traced to a business owner before it can be removed. Ask any provider to itemize the inventory, mapping, testing and handover steps in the quote so you can see where the time goes.
Can our internal team review Superset roles without a partner?
Yes, an internal team can do the work if it has someone who understands Superset's permission model and can read the Flask-AppBuilder permission tables. The team needs access to the metadata database, a staging instance that mirrors production, and authority from the people who own each dataset. The risk for internal teams is not the technical change but the habit of leaving broad roles in place because nobody wants to break a dashboard. A partner can add an outside review of the role matrix, a second set of eyes on the Admin and Alpha assignments, and documented test results. Whichever path you choose, the decision should be recorded so auditors can see who approved each role, and the internal owner should be named before the work starts.
What do we need to provide for a role review?
Prepare three things before the work begins: a role inventory, named access owners, and test accounts. The inventory lists every user, group and IdP mapping, the role each one holds, and any custom role with its permissions. Access owners are the business people who can say which dashboards, datasets and databases each population needs. Test accounts are one representative login per population in a staging environment, so each role can be exercised before and after the change. Without test accounts, a review can only be checked by reading configuration, which misses permissions that only show up when a user opens a dashboard. Also provide the current Superset version, a recent metadata database backup, and the list of dashboards that executives or external users rely on, so those are checked first.
Will changing roles break our dashboards?
It can, and the most common breakage comes from removing a role that a dashboard, chart or scheduled report depends on indirectly. Dashboards depend on the datasets and databases behind them, so a user who loses access to a dataset will see errors even when their dashboard role still looks correct. Reports and alerts run under specific owners, so changing that owner's role can stop delivery. Test each dashboard family as each population in staging, including exports and any embedded use. Plan a short rollback window and keep the previous role configuration so you can restore it. Dashboard-level control is a separate design question covered in the dashboard access control topic, so treat this check as a verification step rather than a substitute for that design.
What happens to our role changes after a Superset upgrade?
Superset's upgrade documentation says to run superset db upgrade and superset init, and the second command re-creates the built-in roles and their default permissions. If you edited a built-in role such as Gamma directly, those edits can be reset, so your changes need to live somewhere that survives. The safer pattern is to create custom roles that inherit from a built-in role and keep the built-in roles at their defaults. Before every upgrade, export or record the role configuration, back up the metadata database, test in staging, and check UPDATING.md for breaking changes between your current and target versions. After the upgrade, rerun your test accounts against each population, because a new release can add permissions that widen access without any visible prompt.
Do we need an identity provider before changing roles?
You do not need one, but an identity provider makes role changes far easier to govern. Superset supports OAuth2 providers, LDAP, and mapping of LDAP or OAuth groups to roles through AUTH_ROLES_MAPPING. When a user's role comes from a directory group, a change is made once in the directory and applied at next login, which gives you a single record for auditors. Without that mapping, every role change is a manual edit in Superset and every departure needs a separate cleanup. If your current login is local accounts, plan the identity integration alongside the role design so the group names you map to are settled before you rewrite roles. Confirm the group claim behavior and login timing with your identity provider's documentation and your own test environment.
Who should approve moving users off Admin or Alpha?
Approval should come from the owner of the data and from the security or platform lead, because each side sees a different risk. Admin users can change almost any part of the instance, while Alpha users can often edit and see more than Gamma users. Ask each Admin or Alpha holder which task requires that role today, then decide whether that task can be handled by a narrower custom role or by a small set of named administrators. Record each decision, the reason, and the approver, so the trail survives staff changes. Expect pushback from people who used broad access for convenience, and resolve it with a documented alternative rather than leaving the broad role in place.
How DeployOpen scopes role design for Superset
DeployOpen scopes a Superset role design as a written deliverable before any role is edited. The work starts with the user populations: who builds charts, who only views published dashboards, who runs SQL Lab queries, who administers the instance and which accounts are service or shared logins. For each population we record the databases and datasets it needs, whether it needs SQL Lab and whether it needs export or embedding rights. That inventory is what decides whether Gamma, sql_lab, Alpha or a custom role fits, and it exposes the common case where Admin or Alpha was granted to people who only needed to view dashboards. Ask any partner to show this inventory before drafting role definitions.
From the inventory, we draft the role definitions and the mapping from your identity provider groups, if you use AUTH_ROLES_MAPPING, to Superset roles. Each draft is tested with sample accounts, one per population, on a staging instance built from the same configuration as production. The tests check what each account can see, open, query and export, and confirm that the custom roles survive a superset init run, since that command resets built-in role permissions. The results, the role matrix, the mapping table and the upgrade check list for the Superset version in use are delivered in writing, with the upgrade check tied to the project's upgrade documentation and UPDATING.md notes for the target release.
Engagements of this kind are fixed-scope. The scope, deliverables, environments and timelines are agreed in writing before work starts, and the quote follows from that scope. Ongoing support is available as a retainer for teams that want help reviewing role changes after each Superset upgrade or when new user populations join. Confirm with your partner which environments they will access, how sample accounts are created and removed, and who approves the final role matrix on your side.
