Role and Permission Management#

Overview#

Superset's role and permission system is built on Flask-AppBuilder (FAB) RBAC, extended by SupersetSecurityManager 1. The core building blocks are:

• Permission — an action name (e.g. can_read, can_write, datasource_access)
• ViewMenu — a resource name (e.g. Dashboard, Chart, a specific database)
• PermissionView (PVM) — a (Permission, ViewMenu) pair stored in ab_permission_view
• Role — a named set of PVMs; users gain access by holding one or more roles

Four built-in roles are managed by Superset: Admin, Alpha, Gamma, and sql_lab. These are rebuilt on every superset init 2. Object-scoped permissions (database_access, schema_access, datasource_access) are never assigned to built-in roles — they are managed per-object via SQLAlchemy event hooks 3.

Scope note: This article covers the schema, management APIs, and utility methods for roles and permissions. For how permissions are initialized/deduplicated see Permission Registration; for runtime access enforcement see Access Control; for frontend propagation see Permission Propagation.

Database Schema#

Superset inherits FAB's five-table RBAC schema 4:

The (permission_id, view_menu_id) unique constraint on ab_permission_view prevents duplicate PVMs. The (permission_view_id, role_id) unique constraint on ab_permission_view_role prevents duplicate role assignments 5.

During Alembic migrations, superset/migrations/shared/security_converge.py provides utilities to rename or restructure PVMs without losing role assignments — see migrate_roles() 6.

Managing Roles and Permissions#

CLI: superset init#

The primary way to provision built-in roles is the superset init command 2, which runs two operations in sequence:

1. appbuilder.add_permissions(update_perms=True) — registers all FAB view/action PVMs in the database
2. security_manager.sync_role_definitions() — rebuilds Admin, Alpha, Gamma, sql_lab role memberships and cleans up orphaned PVMs 7

There are no dedicated CLI commands for exporting or importing roles — role management at the CLI level is exclusively via superset init 8.

REST API#

RoleRestAPI at GET /api/v1/security/roles/search/ lists roles with pagination and filtering 9. RISON query parameters:

Each returned role object includes id, name, user_ids, permission_ids, and group_ids arrays. The endpoint requires the list_roles permission and is admin-only 10.

Full role CRUD (create, read, update, delete) is provided by the inherited FAB RoleApi, exposed via SupersetRoleApi 11. The only Superset-specific override is pre_delete(), which clears item.permissions before deletion to satisfy database constraints.

UI#

RolesListView at /roles/ renders the modern frontend SPA for role management 12. It is registered under the Security menu as "List Roles" 13. The legacy FAB RoleModelView is explicitly removed during security manager initialization in register_views() 14. The SUPERSET_SECURITY_VIEW_MENU config key (default: True) controls whether the Security menu appears at all 13.

Migration-Time Permission Management#

security_converge.py is used inside Alembic migrations to rename or restructure permissions without losing existing role assignments. Key functions 15:

• add_pvms() — creates new Permission, ViewMenu, and PVM records if they don't exist
• migrate_roles() — maps old PVMs to new ones across all roles, then deletes the old records
• _delete_old_permissions() — cleans up orphaned PVMs, permission names, and view menus post-migration

Key Methods in SupersetSecurityManager#

All methods are in superset/security/manager.py 16:

copy_role() accepts either a concrete role name or a builtin role with regex-pattern matching (via _get_pvms_from_builtin_role()). It is used by sync_role_definitions() to optionally mirror a role's permissions onto the Public role via the PUBLIC_ROLE_LIKE config key 17.

Key Source Files#