Why group-to-role mapping decides who can see what in Superset
AUTH_ROLES_MAPPING translates identity provider groups into Superset roles at login, so access follows your directory instead of hand-maintained grants. Teams need it once more than a handful of people use Superset and the same groups already define who may query which data elsewhere. Superset is built on Flask-AppBuilder, and the configuration documentation describes how LDAP or OAuth group claims are mapped to roles through this setting. The mapping decides which dashboards, datasets and database connections a person can reach, so it is an access control decision, not a cosmetic login setting.
The alternative is managing roles by hand inside Superset's own user administration. That works for a small pilot, but every joiner, mover and leaver then needs a manual change in two systems, and roles drift away from the directory without anyone noticing. With mapping at login, the role set is recalculated each time a user signs in, so removing someone from a group in the identity provider takes effect at their next sign-in. The trade-off is that the mapping is only as good as the group structure behind it. Before you write any mapping, confirm with your identity team which groups are maintained for business purposes and which are legacy or nested in ways that will produce unexpected roles.
Plan the mapping as a reviewed artifact, not a quick edit. List each identity provider group, the Superset roles it should grant, and who approves changes to that list. Confirm in the configuration documentation exactly which group attribute your provider sends and how Superset handles users who match no mapped group. Then test with a sample of accounts in staging before production, since a wrong mapping can either lock out analysts or give broad access to data they should not see.
How Superset syncs IdP groups to roles at login
Superset does not query your directory on a schedule. Role assignments are evaluated when a user signs in, so the group claims or LDAP memberships presented at that moment, compared against AUTH_ROLES_MAPPING, decide what the user can do. The cards below follow that flow from the sign-in request through to the users who never return.
What the provider sends at sign-in
With OAuth2 or OIDC providers, group membership usually arrives as a claim in the token that Superset reads during login. With LDAP, Superset searches the directory for the user's group memberships. Either way, the group values Superset receives are the only input to the mapping. Confirm exactly which claim or search your identity provider returns, because a group that exists in the directory but is missing from the token will never reach AUTH_ROLES_MAPPING.
How AUTH_ROLES_MAPPING is applied
Superset compares the incoming group values with the keys of AUTH_ROLES_MAPPING and assigns the Superset roles listed against each match. The mapping is applied when the user signs in, so changes to the mapping take effect at the next login rather than immediately for active sessions. Test with a user in several groups to see how the matched roles combine in your version.
When a group is removed upstream
If a user is removed from a group in the identity provider, Superset does not learn about it until that user signs in again. At that next login the group is absent from the claims, so the role it granted should no longer be assigned. Confirm in your version whether roles added by a previous login are removed or merely left unchanged, since that difference decides whether a former member keeps access.
When a user never signs in again
A user who left the organization and never returns keeps whatever account and roles they already hold in the Superset metadata database. Login-time sync does not remove them. Plan a deprovisioning step that deactivates the account, and confirm with your version how inactive or removed users are treated by the authentication backend before you rely on it.
Testing the sync before rollout
Create a test group in your identity provider, add a test user, and sign in to a staging Superset built from the same configuration. Check the user's roles in the Superset interface after login, then remove the user from the group and sign in again. Record both results so the expected behavior is confirmed in your environment rather than assumed from the documentation.
Confirming behavior for your version
Sync details can change between Superset releases and differ by authentication backend, so the documentation is the starting point, not the final answer. Check the configuration and release notes for the version you run, and review UPDATING.md for changes that affect authentication before any upgrade. Ask your implementation partner to document the observed behavior as part of acceptance.
Mapping design options and when each fits
This table compares four ways to turn identity provider groups into Superset permissions, from one group per role to custom roles with scoped permissions. Read each row for the fit, the ongoing maintenance load and the effect on what an auditor has to review. The main takeaway is that the number of roles you create matters less than whether each role has a name and owner that someone can explain.
| Option | Best fit | Maintenance cost | Audit impact |
|---|---|---|---|
| One-to-one group to role | Small teams where each IdP group already matches one job function and one set of dashboards | Low at first, grows as each new group needs its own role and mapping entry | Easy to trace: one group, one role, one review item |
| Several IdP groups into one role | Organizations with many fine-grained directory groups that share the same Superset access | Lower role count, but changes to group membership rules must be tracked in the mapping | Harder to explain, since the role no longer matches a single directory group; document the grouping |
| Built-in roles such as Admin, Alpha, Gamma and Public | Early rollouts or small administrator sets, where stock permissions are close to what is needed | Low setup, but built-in permissions may be broader than intended and can be hard to narrow later | Reviewers must confirm what each built-in role allows in your version before signing off |
| Custom roles with scoped permissions | Regulated environments that need least-privilege access to specific databases, datasets or features | Highest upkeep: permissions must be reviewed after each Superset upgrade and new feature | Strongest evidence when each role has a documented purpose, owner and permission list |
| Mapping only admins, with a default role for everyone else | Teams that want a strict administrator path and a low-privilege default for self-registered users | Low, but the default role must be checked whenever new permissions are added | Clear split between privileged and general access, which assessors can test directly |
| Mapping that depends on users being in many groups | Users who belong to several IdP groups that imply different access levels | Medium to high: conflicting or overlapping mapped roles need rules and testing | Hard to prove without a test matrix showing which roles a user receives from each group combination |
| Row level security layered on mapped roles | Access that must differ by region, business unit or customer within the same dataset | Recurring: RLS rules must be maintained alongside role changes | Auditors often ask for both the role and the RLS rule for a given user; keep them documented together |
Naming IdP groups and Superset roles so audits stay readable
Platform owners maintain the AUTH_ROLES_MAPPING dictionary and answer for every login that succeeds or fails. They need names that show, at a glance, which environment a group belongs to and whether it grants a Superset role that can change configuration. A useful pattern is a fixed prefix, then environment, then domain, then access level, such as dsp-prod-finance-viewer. Keep the vocabulary short and document it once, so every new group follows the same pattern.
- Fix the segment order: Choose one order, such as application, environment, domain, access level, and apply it to every IdP group and every Superset role.
- Limit the environment values: Use a closed list such as
dev,test,prod, so a production group cannot be mistaken for a staging one. - Separate admin roles: Give Superset
Adminor other high-privilege roles their own groups with a distinct prefix, so they stand out in reviews. - Mirror names where possible: Use the same base string in the IdP and in Superset so a mapping entry reads as one line.
- Version the mapping file: Keep the dictionary in version control so each naming change has a reviewable history.
Before you rely on any name, confirm with your IdP how the group claim is formatted, because the value Superset receives must match the mapping key exactly.
Data stewards own the business meaning of datasets and decide who may see them. For them, a group name should say which data domain it covers and what level of access it grants, in terms they already use. Names that describe a business function, such as finance, claims or marketing, are easier to review than technical identifiers. Stewards should also be able to tell whether a group only grants dashboard access or also grants access to underlying datasets.
- Name domains in business terms: Use the words stewards use in the data catalog, so a group reads as a business area rather than a system name.
- Name access levels consistently: Choose a small set such as
viewer,editor,owner, and define each one in writing. - Flag data-level scope: Where row level security applies, note in the group description which filter or rule the group depends on.
- Record the owner: Each group should have a named steward who approves membership changes.
- Separate sensitive domains: Give regulated or personal data its own domain segment, so reviewers can find it quickly.
Ask the steward to confirm that each domain and access level name matches their catalog before the mapping goes live.
Auditors and compliance reviewers test whether access was granted on approved grounds and whether it matches the documented model. They work backward from a person or a dashboard to a group, then from the group to a role, and they need each link to be obvious. Readable names shorten that trace. The naming scheme should be documented alongside the mapping so that an auditor does not need to ask the platform team what a name means. This document prepares your evidence. It does not replace an independent assessment.
- Keep one name per role: Avoid two groups that map to the same role with different names, since they make the trace harder to follow.
- Keep a mapping register: Record each IdP group, its Superset role, its approver and the date it was last reviewed.
- Use stable identifiers: Avoid names that embed personal names, project codes that change or temporary labels.
- Capture the naming standard: Store the convention as a controlled document that auditors can read alongside the configuration.
- Test a sample trace: Pick a user and show the chain from the IdP group, through the
AUTH_ROLES_MAPPINGentry, to the Superset role and its permissions.
Ask your auditors which evidence format they accept, and confirm how your IdP presents group claims before you draft the register.
Setting up AUTH_ROLES_MAPPING step by step
This sequence turns an agreed access model into a working AUTH_ROLES_MAPPING, so each identity provider group grants a known set of Superset roles at login. It also leaves a tested, version-controlled configuration that a reviewer can trace from group to role.
Inventory the identity provider groups
Export the groups that could grant Superset access from your identity provider or directory, including their exact names, membership counts and owners. Ask the identity team which groups are maintained for business purposes and which are legacy, nested or empty. Done means you hold a list of candidate group names, each with an owner who can confirm its purpose.
Decide the role model
Working with the data owners and the Superset administrators, decide which Superset roles each business function needs, such as viewing dashboards, building charts, or administering the instance. Keep the built-in roles where they fit and add custom roles only for gaps. Record which groups map to which roles and which groups should map to nothing. Done means a written table exists that both teams have signed off.
Create or confirm the Superset roles
In the Superset interface or through your deployment tooling, confirm that every role named in the table exists, with the permissions you intend. Check role names for exact spelling and case, because AUTH_ROLES_MAPPING matches on the string. Done means each role appears in the role list and a test user assigned to it can see only the expected menus and data.
Configure the group claim or LDAP group search
For OAuth or OIDC, configure the identity provider to include group membership in the token or userinfo response, and confirm the claim name your Flask-AppBuilder provider block reads. For LDAP, configure the group search so Superset can read group membership for each user at login. Note any group limits your IdP imposes on tokens. Done means a test login returns the expected group values in the logs or a debug view, not just the group names you expected.
Write AUTH_ROLES_MAPPING in superset_config.py
Add the mapping to superset_config.py as a dictionary from the exact IdP group string to a list of Superset role names, following the form shown in the configuration documentation. Set the sync behavior required by your login provider and keep secrets out of this file. Restart the web and worker processes so the change loads. Done means the configuration starts without error and the mapping matches your signed-off table line for line.
Set default roles for new users
Decide what a user with no mapped group receives at first login. Set the default role for self-registered users in the provider configuration, and keep it to a read-only role or none. Confirm whether users with no matching group can log in at all, since that depends on your provider settings. Done means a user from a group you did not map lands with only the default role, and a user from no group gets the outcome you chose.
Test with one account per group
Create or use one test account in each mapped group, plus one account in no group and one account in several groups. Log in as each, then check the roles shown on the user record, the dashboards visible and the charts that can be built. Remove a test account from a group and log in again to confirm roles are removed at the next sync. Done means every test account matches the expected results in a written test record, and you have seen one role change propagate.
Record the mapping in version control
Commit the mapping, the role definitions and the provider block to the repository that holds your Superset configuration, and require review for changes. Store the signed-off role table with it so auditors can trace each group to its roles. Run the test accounts again after every change to the mapping. Done means the repository history shows who approved each group-to-role line and the test record is linked to the commit that passed it.
Default roles for new users and users with no mapped group
A user who signs in with no matching group receives only the roles that Superset grants by default at login, and the answer depends on how your authentication provider is configured. In Superset, the Flask-AppBuilder layer decides whether an account is created on first sign-in and which role it starts with, while AUTH_ROLES_MAPPING only adds roles when a group matches. When a user matches no mapping, the mapped roles are simply absent, so the account's access is whatever the default or self-registration path assigned. Treat that default as a security decision in its own right, because it applies to every person who can authenticate through the provider, including people you never intended to give access to.
A broad default role is the most common way access drifts beyond the group model. If the default is a role that can read many datasets or open the SQL editor, every employee, contractor or external account that reaches the login page inherits it, and mapped roles only add to that baseline. Keep the default minimal, ideally a role with no dataset access beyond what a generic landing experience needs, and let explicit group membership grant everything else. Confirm the self-registration and new-user settings for your provider in the Superset configuration documentation and in the provider itself, since whether sign-in creates accounts, and whether the provider lets anyone authenticate, can be controlled on either side. Do not assume the defaults match your policy.
Review accounts that hold no mapped role on a regular schedule, and before go-live, list every Superset user whose roles came only from the default. Compare that list with your directory to find accounts for people who left, were never provisioned into a group, or are service identities that should not exist as interactive users. Decide in advance what happens to them: disable, move to a holding role with no data access, or map them to a group that someone owns. Record the review and its owner, since auditors testing access control usually ask how orphaned accounts are found and removed, not only how groups are mapped.
Combining mapped roles with row level security
Mapping identity provider groups to Superset roles controls which features and datasets a user can reach, but it does not limit which rows a user sees inside a dataset they are allowed to query. Row level security (RLS) is the separate control that appends filter clauses to queries per user or role. A user in a mapped group that grants access to a sales dataset can still see every row of that dataset unless an RLS rule applies to one of their roles. Plan both layers together: the group mapping decides who gets in, and RLS decides what they see once inside.
In Superset, RLS rules are defined against a dataset and attached to one or more roles, so a rule takes effect for any user who holds that role, including roles assigned through AUTH_ROLES_MAPPING at login. When a user belongs to several groups, they receive the union of their roles, and the filters on those roles are combined. Confirm in your Superset version how multiple RLS clauses from different roles are joined, since the result determines whether a user in two groups sees the wider or the narrower set of rows. Also confirm whether the rules apply to guest users in embedded dashboards, which use a separate access path.
Test this before rollout with one test account per group combination you expect, including a user in two groups that carry different filters. For each account, run the same chart or SQL Lab query and compare the row counts and sample values against what the access model specifies. Check the result against the database directly, since the test confirms what Superset applies, not what your data policy requires. Repeat the test after every Superset upgrade, because RLS behavior is part of the release notes you should review in UPDATING.md before moving versions.
Handling users who belong to many groups
How do multiple matching groups combine into Superset roles?
Superset adds every role that matches one of the user's groups, so a user in three mapped groups receives the union of those three roles. Flask-AppBuilder applies the mapping at login, and the permissions a user ends up with are the sum of all assigned roles. There is no priority order between groups that decides one role over another, which means the most permissive group defines the effective access. Before you map anything, list which groups grant which roles and check the combined result for your most common user profiles. Confirm the exact sync behavior for your Superset version in the configuration documentation.
When should we create a combined role instead of stacking mapped roles?
Create a combined role when a set of permissions only makes sense together and users should never hold one part without the other. For example, an analyst who needs a specific dataset and a specific dashboard group might get a single role that bundles both, instead of two separate roles that could be granted independently. Combined roles are easier to review because auditors can read one role definition, and they reduce the chance that a user receives a partial set of permissions by accident. Keep combined roles narrow, name them after the job they support, and document which directory groups feed them.
How do we prevent privilege creep when users change teams?
Privilege creep happens when a user keeps roles from old groups because the mapping only adds roles and never removes them. Superset applies the mapping at login, so a user who leaves a group loses that role only when the mapping is refreshed, and only if your configuration removes roles that no longer match. Review how your Superset version handles role removal at login, then test it with a user you move between two groups. Pair this with periodic reviews of group membership in your identity provider and with a deprovisioning process for people who leave the organization.
What should we do about nested groups in the directory?
Superset compares the group names it receives in the login claims or LDAP search results, so a group nested inside another group only counts if its membership is returned directly to Superset. Many directories expand nested membership in the directory itself, while others return only direct memberships. Test a user who belongs to a nested group and confirm the claim or search result includes it. If nesting is not returned, either flatten the group structure for Superset or ask your identity team to expose the effective membership. Document the decision because a silent gap here can grant too little access or, in rare designs, too much.
How do directory group limits affect the group claims Superset receives?
Some identity providers limit how many group values they place in a token, and when a user exceeds that limit the provider may omit the groups claim and send a signal instead. In that case Superset receives no groups and maps the user to default roles, which can look like a permission problem rather than a token problem. Check the group overage behavior of your provider, decide whether to filter the groups sent to the application, and test with a user who belongs to a large number of groups. Ask your identity administrator which claim is returned in this case and whether the application can fetch the full list directly.
Can row level security replace group-based role mapping for many users?
Row level security and role mapping solve different problems, so they usually work together rather than substitute for each other. Role mapping decides which features and datasets a user can reach, while row level security filters the rows returned from a dataset based on rules you define. A user in several mapped groups still receives the row filters that apply to each of their roles, so review how filters combine before you rely on them. Test a user from each group on the same dashboard and compare the results against the data they should see.
Who should review the mapping for users in many groups?
A reviewer from the data owner's side should approve which directory groups grant which Superset roles, and the identity team should confirm how groups arrive at login. Security or compliance staff should review the combined access for high-sensitivity datasets and check that the review produces evidence, such as a dated list of mappings and test results. DeployOpen can plan this review and prepare the test cases and evidence as part of a fixed-scope engagement, but the access decisions remain with your organization. Ask any implementation partner to confirm in writing who signs off on the final mapping.
Security and operational risks in group-based access
Group-based access moves authorization decisions from Superset into your identity provider, so the risks sit at the seams: when sessions outlive group changes, when mappings grant more than intended, and when the people who change them are not reviewed. The cards below cover the items to design and test before rollout, not after the first access review.
Stale sessions after group removal
Superset assigns roles from the groups it sees at login, so a user removed from a group keeps that role until their session ends or the next sync. Confirm how your Flask-AppBuilder version refreshes roles, set session lifetimes you can defend, and test the removal path with a user who is still logged in. Treat the gap between removal and the next login as the exposure window you must document.
Overly broad Admin mapping
A single IdP group mapped to the Admin role can grant full control of databases, users and security settings, often to a group created for a different purpose. Map only the groups that own a documented need for administrative rights, and review membership of any group that reaches Admin on a fixed schedule. Ask whether the mapping grants Admin by default for any group whose membership is not tightly controlled.
Missing break-glass admin
If the IdP is unavailable, misconfigured or its group claims change shape, nobody may be able to sign in as an administrator. Keep a local break-glass account, store its credentials under dual control, and test that it still works after each change to the login configuration. Confirm that the account is excluded from automated deprovisioning so it survives directory cleanups.
SECRET_KEY and session handling
Superset requires a user-specified SECRET_KEY to start, and session integrity depends on that key staying stable and private. Store the value in a secrets manager, not in a config file committed to source control, and plan rotation with PREVIOUS_SECRET_KEY so existing sessions do not all fail at once. Changing the key without a rotation plan can also invalidate the sessions that the group sync depends on.
Mapping changes reviewed like code
AUTH_ROLES_MAPPING decides who can see which data, so a change to it is an access change. Keep the mapping in version control, require a second reviewer for any change that adds a role to a group, and link each entry to the owning team. Record who approved each change so the access review can trace a role back to a decision.
Operational work on upgrades and backups
Role mappings and user assignments live in the metadata database, so an upgrade or restore can change access without anyone noticing. Before each upgrade, back up the metadata database, follow the upgrade steps in the project guide, and check UPDATING.md for breaking changes. Afterward, compare the role assignments for a sample of test users against the expected mapping in staging.
Questions buyers ask before outsourcing group mapping
What drives the cost of mapping identity provider groups to Superset roles?
The cost follows the number of groups, the number of identity providers and the amount of access logic that has to be designed, not the single configuration line. The main drivers are how many groups exist in the directory, how many of them must map to Superset roles, whether some users belong to many groups, and whether row level security rules must be aligned with each role. Ask any provider for a quote that lists the group inventory it assumed, the environments covered (staging and production), the testing it includes and who performs the IdP side of the work. One-time design and build work is separate from any recurring support or review of group changes.
How long does a group-to-role mapping project usually take?
The duration depends on how quickly the organization can agree on its role model and how many directory groups need decisions, so no fixed timeline applies to every environment. Most of the elapsed time usually sits in access decisions and approvals rather than in the Superset configuration itself. Ask for a schedule that separates the group inventory, the role design, the staging test cycle and the production cutover, and confirm which steps depend on your IdP administrators' availability. Any timeline in a written scope should be tied to those dependencies.
What do we need to give the implementation team before work starts?
The team needs administrative or read access to the identity provider's group and claim configuration, a complete group inventory with owners and purpose, and a current list of the Superset roles in use. It also needs a staging Superset instance that matches production authentication settings, and a named approver for the access model. Without the IdP group inventory, the team cannot tell which groups are security-relevant and which are stale. Confirm with your IdP administrators whether group claims are emitted in tokens, whether they are filtered, and whether nested groups are flattened before they reach Superset.
Can our internal team set up group mapping without outside help?
Yes, an internal team with Superset administration skills and IdP administration access can usually do the configuration itself, provided it has time to design and test the role model. The harder part is governance: deciding which group grants which access, documenting it and proving that changes were reviewed. Outside help is most useful when the directory is large, when several identity providers feed one Superset, or when auditors will test the access model. Whichever path you choose, ask the partner to separate design, build and test deliverables in the written scope so your team can see what it has inherited.
How do we test that users get the right roles after mapping?
Test with a fixed set of test accounts, one per access profile, and check the roles and data each account can see after it signs in. Cover users in one group, users in several groups, users in no mapped group and users who have just left a group. Repeat the test after any change to the group claim, the AUTH_ROLES_MAPPING block or the row level security rules, and keep the results as evidence. Staging should run the same Superset version and authentication settings as production, since Superset upgrades are tested in staging first according to the upgrade documentation.
What goes wrong when a user belongs to many identity provider groups?
A user in many groups can receive more roles than intended, and the combined permissions can be hard to predict. Some directories also limit how many group claims they will include in a token, so a user may log in with an incomplete set of roles and no obvious error. Plan the mapping so each group maps to a narrow, named role, avoid granting broad administrative roles through group membership, and document which roles combine. Confirm with your identity provider how group overage is handled, because the answer decides whether Superset can rely on the group claim at all.
How do mapped roles interact with row level security?
Mapped roles decide which features and datasets a user can reach, while row level security filters the rows returned from those datasets, so the two must be designed together. A role that grants access to a dataset does not by itself limit which rows a user sees, and a filter that depends on a role name breaks if the role is renamed. Keep role names stable and documented, then review each row level security rule against the roles it applies to. Ask the provider to show the test cases that prove a user in one group cannot see rows reserved for another.
What should we set for default roles and users who are not in any group?
Set the default role to the least privileged role that still lets a new user reach the application, and do not let an unmapped account inherit broad access. Decide whether a user who signs in without a mapped group should be refused, shown a limited role or sent to an administrator for review. This choice affects onboarding, support load and audit findings, so record it in the access model. Confirm the exact behavior in your Superset version and login method against the configuration documentation before you rely on it.
Does the mapping keep working when group membership changes?
Roles are typically refreshed when users log in, so a removed group membership takes effect at the user's next sign-in rather than instantly. Existing sessions can keep their old access until they expire, so the session lifetime and any forced sign-out process matter for leavers and for access reviews. Ask the implementation team to document how a removal propagates, and agree who owns group changes after go-live. Verify this behavior with your identity provider and login method in staging before you rely on it for offboarding.
How DeployOpen scopes and delivers group-to-role mapping
DeployOpen starts from the group names and access rules your identity provider already holds, then designs the AUTH_ROLES_MAPPING entries, default role and role boundaries in your own Superset environment. Engagements are fixed-scope, with the deliverables agreed in writing before work begins.
How we scope
- We inventory the IdP groups that should grant Superset access and confirm which of them are maintained by owners you trust.
- We agree in writing which roles each group maps to, the default role for new users and how multi-group users are handled.
- We define what is out of scope, such as directory changes, Superset database connections and RLS rule authoring, so the quote matches the work.
How we build
- We configure the OAuth or LDAP provider settings and AUTH_ROLES_MAPPING in your deployment, then test each group against a staging instance.
- We check login-time role sync with test accounts covering single-group, multi-group and no-group users, including removal of a group.
- We verify that mapped roles combine with row level security as intended, using accounts that hold the same roles your users will hold.
How we hand over
- We document the group-to-role table, the naming convention for groups and roles, and the steps to add a new group safely.
- We provide the test cases and results so your team can repeat the role checks after changes to the IdP or Superset version.
- We walk your identity and platform staff through ownership of the mapping, including who approves changes to group membership.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, so role mappings can be re-tested after Superset upgrades.
- We can review the mapping again when your IdP group structure changes, such as after a reorganization or a new application rollout.
- Support scope, response expectations and fees are set in a written agreement, and we confirm them with you before any changes are made.
