Custom Superset roles for dataset and database access

Custom Superset roles for dataset and database access: when Gamma is not enough

Build a custom role when analysts need some datasets or schemas but not everything, and the built-in roles cannot express that split. Gamma is the standard read-oriented role in Superset. Its users can open the dashboards and charts they have been granted and query the datasets attached to them, but it does not, by itself, decide which databases or tables a team sees. Teams usually reach the limit of Gamma in one of two ways: it is too broad because every Gamma user inherits access to datasets they should not query, or it is too narrow because a new analyst group needs a few more datasets than Gamma allows without granting write or admin capability.

A custom role layers specific permissions on top of Gamma. In practice you add dataset-level datasource access grants for named datasets, or schema-level grants for a database, and attach the role to the users or to a group mapped through your identity provider. Because the role is a set of permissions rather than a copy of Gamma, you can scope it to one sensitivity level, one business area or one database connection. Confirm the exact permission names and the current behavior in the Superset version you run, since role administration has changed across releases and the Superset documentation covers the current model.

Before you create a role, list the populations and the datasets each one needs, then decide which of those grants are per-dataset and which are per-schema. Avoid granting the all_database_access permission to a custom role unless you intend that role to query every connected database, because the behavior of that permission changed in Superset 4.1.0 to grant access to the data in all databases, not only the list of them. Check the Superset UPDATING notes for the version you plan to run, and test each custom role with a non-admin account before you give it to users.

Which permission scope fits which access need

This table compares four ways to grant data access in a custom Superset role, from narrowest to broadest. Read each row to see what the scope exposes, when it fits, and how much upkeep it adds as new datasets arrive. The main takeaway is that the narrowest scope that serves the group is usually the one to keep, and that broad grants need a named owner and a review date.

Scope	What it exposes	When it fits	Maintenance as datasets grow
Per-dataset	Only the specific datasets listed in the role, including their columns and the rows the warehouse account can read	A small group needs a fixed set of reports, or one team must see a single sensitive table	High. Every new dataset needs a grant, and each grant must be checked against the request that justified it
Per-schema	All datasets and tables in the named schema, including any added to it later	A team owns one schema, such as a finance or marketing area, and new tables there should be visible to them	Moderate. New tables appear automatically, so the schema boundary must match how data owners organize their work
Per-database	Every dataset registered under one Superset database connection, across all schemas that connection can reach	A group works across one warehouse connection and the connection itself is already scoped by the warehouse account	Low to moderate. Access follows the connection, so a loosely scoped warehouse account widens exposure without a Superset change
all_database_access	Data in every database registered in Superset. Since Superset 4.1.0, this permission grants access to the data, not only to the list of databases (Superset UPDATING notes)	Rarely appropriate outside a small platform administration group that has been explicitly approved	Low effort, high risk. It bypasses per-dataset and per-schema intent, so every new database connection silently widens who can read it
Permission names	Exact names for these grants vary by version and by how the role was created	Before building roles, confirm the names in your installed version	Check the Superset permissions list in your own instance and record the names used in your role configuration
Upgrade stability	Custom roles are edited in the metadata database, and some upgrade steps re-run initialization	Any time a role is built on top of Gamma or other built-in roles	Keep a written list of grants per custom role and verify it in staging after each upgrade, following UPDATING.md

Why all_database_access changes what users can read

The all_database_access permission is the broadest grant a custom role can hold in Superset, and its meaning changed in 4.1.0. The cards below explain that change, the exposure it creates on shared warehouses, and the checks reviewers should run on any role that carries it.

The 4.1.0 meaning change

Before Superset 4.1.0, all_database_access let a role list every database connection without necessarily reading the tables inside them. Since 4.1.0 it grants access to the data in all databases. A role definition that looked harmless on an older instance can therefore expose far more after an upgrade, so reviewers should re-read every role that holds it on any version change.

Shared warehouses with sensitive schemas

When one warehouse connection serves several teams, a role with all_database_access can query schemas that hold payroll, customer identity or regulated health data, even if its dashboards never touch them. Dataset-level grants do not narrow this permission. Confirm which schemas sit on each shared connection and whether any sensitive schema is reachable through the same credentials Superset uses.

Who holds the permission today

Audit every custom role and every user assigned to one, and record which ones include all_database_access. Built-in roles and inherited grants can hide it, so check the effective permissions rather than only the role names. Ask the platform team to produce this list from the metadata database before any access review, and keep it as evidence for the next review cycle.

Reviewer checks for each grant

For any role that holds the permission, reviewers should ask four questions: which users need cross-database reads, which databases they actually use, whether a narrower grant on specific datasets or schemas would serve the same work, and who approved the exception and when it expires. A written justification tied to a named business owner is the minimum record worth keeping.

Narrowing to dataset and schema grants

In most cases the safer design is to grant read access per database, schema or dataset within a custom role and to keep all_database_access out of it entirely. Illustrative example: an analyst role that needs one sales schema on one warehouse gets that schema's datasets, while a separate reporting role gets its own grants. Test each narrowed role with a real analyst account before rollout.

Keeping the grant stable across upgrades

Because role contents can change with a release, store the role definition and the list of granted permissions in version control, compare them after each upgrade, and re-run the access checks in staging before production. Confirm with the vendor or the upgrade notes which permission names changed in the target version, since a renamed permission can silently widen or narrow access.

Combining Gamma with custom roles without widening access

Start by cloning Gamma into a named role for one business area, then change only what that group needs. Gamma is a built-in role that superset init resets, so edits made directly to it are lost on the next run, and a separate copy keeps your changes in one place. Keep the cloned role narrow, because a role with a short, reviewed permission list is easier to audit than one copied from a broad template.

Clone, do not edit, Gamma: Create the custom role from a copy so the built-in baseline stays intact.
Add dataset grants explicitly: Grant datasource_access on the specific datasets the group should query.
Use schema grants only for whole schemas: Add schema_access only where every table in that schema is meant for the group.
Keep database-wide access out of analyst roles: The topic facts note that since Superset 4.1.0, all_database_access grants access to the data in all databases, so it should stay out of role sets meant for analysts.
Document each permission: A short reason beside each grant speeds up later reviews and upgrade checks.

Before assigning the role to real users, log in as a test user who holds only this role and confirm that the dataset list matches the design.

When login is handled by an identity provider, roles often arrive through group mapping rather than manual assignment. The AUTH_ROLES_MAPPING setting maps identity provider groups to Superset role names. Each group in the mapping carries its roles to every member, so a mapping that points at a broad role gives that access to the whole group at once. Group mapping is convenient, but it moves the access decision into the identity provider, and the mapping itself becomes a control to review.

Map to narrow roles only: Point each identity group at a custom role that matches its purpose, never at Admin or Alpha by default.
Confirm role sync behavior: Check in your version whether AUTH_ROLES_SYNC_AT_LOGIN is set, because without it, roles may persist after a user leaves a group.
Keep the mapping in version control: Changes to group-to-role rules should go through the same review as other access changes.
Test the removal path: Remove a test user from a group in the identity provider and confirm that the role disappears in Superset.
Map unions carefully: A user in several groups receives the union of all mapped roles, so check overlapping groups.

For the exact mapping syntax and sync options, read Configuring Superset for your release and confirm them in staging.

Because permissions combine, the only reliable proof of access is to test what each user can actually see and run. Build an access matrix that lists each role combination, the datasets and databases it should reach, and the datasets it should not reach. Then test the matrix in a staging instance that uses the same role definitions and identity mapping as production, so the results carry over.

Create one test account per combination: Give each account only the roles in the matrix row it represents.
Test negative cases: Confirm that each account cannot see datasets, charts or databases outside its row, since missing denials are the usual failure.
Check the warehouse side too: Confirm that the database account behind each connection cannot read more than Superset exposes.
Repeat after changes: Rerun the matrix after any role edit, identity mapping change, superset init or upgrade.
Keep the results with the change record: Store the matrix and the date of each run so auditors can see what was tested.

If your release offers a way to list the permissions a role holds, use it alongside these user tests, and confirm the command or screen in your own version.

Building and testing a custom role step by step

This sequence turns a sensitivity inventory into a named custom role that grants only the datasets and schemas a group needs, then proves from a non-admin account that the grants work as intended. Each step ends with a check, so errors surface before users log in.

Inventory datasets and schemas by sensitivity
Before touching Superset, list every database, schema and dataset the target users need, and tag each one by sensitivity with the data owner's agreement. Include datasets that are virtual, built from SQL, or shared through other dashboards, because they can expose the same rows under a different name. The step is done when every planned dataset has an owner, a sensitivity label and a named user group that will read it.
Clone Gamma into a named custom role
In the Superset UI under List Roles, copy the built-in Gamma role and give the copy a name that states its purpose, such as a team or data domain prefix. Do not edit Gamma itself, because superset init resets edited built-in roles during upgrades. Check that the clone shows the same permissions as Gamma before you change anything, so later differences are traceable to your edits.
Add only the required data permissions
Grant datasource access on the specific datasets, or on a single schema where the whole schema is approved, and avoid broad database-level grants. Review every permission entry in the clone and remove anything that is not needed for the group's dashboards. Confirm that the role does not include all_database_access, and that no grant is given that opens other databases. The step is complete when the permission list matches the inventory from step one.
Document the role and its intended scope
Record the role name, the datasets and schemas it covers, the owner who approved access, and the date of the last review in a location your team controls, such as a configuration repository or access register. Note the Superset version the role was built on. This record is what lets you rebuild the role after an upgrade and show an auditor what the role was meant to allow.
Assign test users and combine roles deliberately
Create two or three test accounts with the custom role and no other data roles, then assign any additional roles, such as sql_lab or a dashboard role, one at a time. Each added role widens access, so record what each combination unlocks. Confirm that no test account holds Admin or Alpha. The step is done when the test accounts have exactly the roles listed in your access register.
Verify effective access from a non-admin account
Sign in as a test user, not as an administrator, and open the datasets in the approved list. Then attempt to open a dataset outside the list, query an unapproved schema in SQL Lab if that role allows SQL Lab, and open a dashboard built on a restricted dataset. Expected results are a successful load for approved items and a denial for everything else. Repeat the checks for each test account, and keep the results as evidence.
Retest the role after each upgrade
After any Superset upgrade or change to the role, repeat the verification from the previous step and compare the results with the recorded baseline. Check the project's UPDATING.md notes for changes to permissions before the upgrade starts, and run the upgrade in staging first. The step is done when the role's effective access matches the baseline in staging and production, and any difference has been reviewed and either fixed or accepted by the data owner.

Keeping custom roles stable across Superset upgrades

Custom roles survive an upgrade only if you treat the role model as part of the release, not as configuration that sits untouched in the metadata database. The upgrade guide asks you to back up the metadata database, run superset db upgrade, run superset init, test in staging first, and read UPDATING.md for breaking changes. The step that matters for roles is superset init. It recreates the built-in roles and syncs their permissions to the current release. If your team edited Gamma, Alpha or another built-in role to add dataset grants, those edits can be reset or altered when the init step runs, and the reset is silent unless someone checks. Treat built-in roles as read-only baselines and put every customization into a role with its own name, such as analyst_finance_sales, which superset init does not overwrite.

Before each upgrade, record every custom role definition as code or as an exported set of permissions, and store it in version control next to your deployment configuration. Capture the role name, the permission set (including datasource_access grants on specific datasets, schemas or databases), and any AUTH_ROLES_MAPPING entries that point identity provider groups at those roles. Then, after the upgrade completes in staging, compare the live role state against that record. Note that UPDATING.md may describe changes to permission names or to the meaning of grants such as all_database_access, so read the entries for every version between your current release and the target before you apply the change.

After each upgrade, rerun a permission test suite against staging and then production. Log in as a representative user for each role and confirm that they can open the datasets they should see, cannot open a neighboring schema, and cannot list or query databases outside their scope. Confirm that new datasets added during the upgrade period did not inherit access they should not have. Ask your Superset implementation partner, or your own platform team, to name who owns the test script and who signs off on the result. Keep the test results with the change record, because the same evidence supports later access reviews.

Security and operational risks of custom role design

Custom roles give Superset precise data access, but the same flexibility lets permissions drift, expose data through shared objects and rely on credentials outside Superset's control. The cards below cover the risks to design for and the checks to schedule before and after go-live.

Permission creep in custom roles

Roles tend to grow as teams ask for one more dataset or database during a project. Each addition is small, but over months a role can cover far more schemas than its original owners intended. Compare each custom role against the access request that created it, and record who approved every added permission so that removals can be justified later.

Shared datasets leak across dashboards

A dataset permission grants access to the dataset wherever it appears, including dashboards owned by other teams that reuse it. A user who can read a dataset may therefore see figures they were never meant to see through someone else's chart. Before granting dataset access, list the dashboards and saved charts that depend on that dataset and confirm each audience is allowed to see its rows.

Reliance on the warehouse account

Superset checks its own role model before running a query, but the warehouse account behind the database connection decides what the data layer can return. If that account can read every schema, a Superset role that is limited to one dataset still runs with broad rights underneath. Ask the data owner which account each connection uses, what it can read, and whether Superset role design and warehouse grants match.

Privileges granted through all_database_access

The all_database_access permission has a broader meaning than many administrators expect. Superset 4.1.0 changed it to grant access to the data in all databases, where earlier versions only allowed listing them. Treat this permission as a near-administrative grant, keep it out of custom roles that are meant for a single team, and recheck it after every upgrade.

Access reviews that never happen

Roles and memberships change through project work, but few teams schedule a regular review of who holds which role. Stale accounts, contractors who moved on and roles copied from old templates remain active. Set a review cadence with the data owners, export role memberships and dataset grants for each review, and remove access that the owner cannot justify.

Upgrades that alter role behavior

Permissions and role definitions can change between Superset releases, so a role that worked on one version may grant different access after an upgrade. Keep custom roles defined in version-controlled scripts, read the breaking changes in the release notes for each target version, and rerun a permission test set in staging before production moves.

Custom role questions teams ask before hiring help

What drives the cost of building custom Superset roles?

The main drivers are how many datasets and schemas need distinct access, how many sensitivity tiers you run, how many identity groups already exist in your directory, and how often you upgrade. Each dataset or schema that needs its own rule adds design, testing and documentation work. Each sensitivity tier adds another role combination to verify. Existing identity groups can shorten the work if they map cleanly to Superset roles through AUTH_ROLES_MAPPING, and they add work if they do not. Upgrade cadence matters because every upgrade requires re-testing the role set. Ask any provider for a quote that lists these inputs separately, so you can see which ones move the price.

How long does a custom role build take?

Duration depends on the same inputs as cost: dataset count, schema count, sensitivity tiers, identity group quality and the test effort you require. A small set of roles for one database with clear owners is a much shorter piece of work than a multi-database model with row-level rules and several user populations. We do not state a fixed duration here. Ask for a timeline in the written scope, and check that it includes time for data owner review, staging tests and a dry run of your next upgrade.

Can our internal team build custom Superset roles without outside help?

Yes, a team with Superset administration experience and access to the metadata database can build roles internally. The work is mostly careful permission design, testing with real non-admin accounts and documentation. The risks are predictable: over-granting through all_database_access, forgetting that a dataset grant also exposes data through shared dashboards, and losing edits when superset init resets built-in roles. Teams that build alone usually benefit from a second reviewer who has not designed the model, and from a written test matrix covering each role and dataset pair.

What do we need to provide before the role work starts?

Plan to provide three things. First, data owners who can state which users should see which datasets, and who approve the rules. Second, a schema inventory listing databases, schemas, datasets and the sensitivity of each. Third, test accounts in your identity provider or in Superset for each user population, plus read-only warehouse credentials for testing. Without named owners, the work stalls at design. Without test accounts, the role set cannot be verified before release.

How do identity groups affect the role design?

Identity groups decide how roles are assigned to people. If your directory already has groups that match your access rules, you can map them to Superset roles with AUTH_ROLES_MAPPING and reduce manual assignment. If groups are organized by org chart rather than data access, the design usually needs a mapping layer or a cleanup in the directory first. Confirm the directory type, the group attribute that carries role information, and whether group membership refreshes at each login. These details change the build more than most teams expect.

Will custom roles break when we upgrade Superset?

They can. Superset upgrade notes list breaking changes between versions, and the project's UPDATING.md file is the place to check permission-related changes before each upgrade. Custom roles also need to survive superset init, which resets built-in roles, so custom roles should be defined separately from the built-in ones. Plan to re-run your permission test matrix after every upgrade, in staging first, and back up the metadata database before running superset db upgrade and superset init.

What recurring work comes after the roles are built?

Recurring work includes reviewing access when people change teams, adding permissions for new datasets, re-running the test matrix after upgrades and patches, and reviewing whether any role has grown beyond its intent. Some of this is routine administration your team can keep. Some needs a periodic review with data owners. Ask any provider whether they offer ongoing support or retainers, and what the work covers when a new database is connected or a new upgrade ships. Support terms are set in the written scope, not assumed.

Which parts of the role model should we ask a provider to verify?

Ask for verification of the combinations most likely to leak data: a non-admin user with a dataset grant who can still see restricted data through a shared dashboard, a user with database-wide access granted by all_database_access, and a user who can export results they can view. Also ask for a check that custom roles survive a superset init run. The written scope should name each test case, the account used, the expected result and the evidence you will receive.

How DeployOpen scopes and delivers custom Superset roles

DeployOpen plans, builds, tests and documents custom Superset roles for dataset and database access inside your own infrastructure. Each engagement starts from a written scope that maps your data domains and user populations to roles, then delivers those roles with tests and handover material your team can maintain after the upgrades ahead.

How we scope

We map which datasets, schemas and databases each user population needs to query.
We identify where all_database_access or broad Gamma grants would exceed what each group should see.
Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.

How we build

We build custom roles on top of Gamma in your Superset instance, using the permissions each dataset requires.
We check role combinations for overlapping grants and confirm effective access per user population.
We test access with named test accounts and record expected and actual results for each role.

How we hand over

We document each role, its permissions, its owner and the reasons behind each grant.
We provide role definitions as scripts or configuration so changes can be reviewed and reproduced.
We walk your team through the upgrade checks needed to keep custom roles stable across releases.

How we support

Ongoing support, upgrades and continuous testing are available as retainers for role changes after go-live.
We can rerun access tests after each Superset upgrade or new dataset is added.
Ask any provider to confirm how role changes are reviewed, approved and recorded in your environment.

Custom Superset roles for dataset and database access