Role-Based Access Control

Relevant source files

• api/commands/rbac.py
• api/configs/app_config.py
• api/configs/deploy/__init__.py
• api/configs/enterprise/__init__.py
• api/configs/extra/notion_config.py
• api/configs/extra/sentry_config.py
• api/configs/remote_settings_sources/enums.py
• api/controllers/console/workspace/rbac.py
• api/models/account.py
• api/models/api_based_extension.py
• api/models/dataset.py
• api/models/model.py
• api/models/oauth.py
• api/models/provider.py
• api/models/source.py
• api/models/task.py
• api/models/tools.py
• api/models/trigger.py
• api/models/web.py
• api/models/workflow.py
• api/services/enterprise/base.py
• api/services/enterprise/enterprise_service.py
• api/services/enterprise/plugin_manager_service.py
• api/services/enterprise/rbac_service.py
• api/tasks/initialize_created_app_rbac_access_task.py
• api/tests/unit_tests/controllers/console/workspace/test_rbac.py
• api/tests/unit_tests/services/enterprise/__init__.py
• api/tests/unit_tests/services/enterprise/test_enterprise_service.py
• api/tests/unit_tests/services/enterprise/test_plugin_manager_service.py
• api/tests/unit_tests/services/enterprise/test_rbac_service.py
• api/tests/unit_tests/services/enterprise/test_traceparent_propagation.py

Purpose and Scope

This document provides a detailed technical overview of Dify's Role-Based Access Control (RBAC) system. The RBAC system governs user permissions and access within multi-tenant workspaces, defining a hierarchy of roles through the TenantAccountRole enum. It supports five roles: OWNER, ADMIN, EDITOR, NORMAL, and DATASET_OPERATOR.

The system integrates tightly with an enterprise-grade RBAC service to allow fine-grained resource permission checks. This page explains role definitions, the tenant-account role association model, enterprise RBAC integration, permission validation wrappers, and summarizes the permission matrix applied across the platform.

For related details on tenant modeling, authentication, and workspace management, see:

• 8.1 Tenant Model and Resource Isolation
• 8.2 Authentication Methods and Flows
• 8.4 Workspace and Member Management

---

Role Hierarchy

Dify defines workspace roles via the TenantAccountRole enum in api/models/account.py. Roles express increasing levels of privilege and scope:

• OWNER: Full workspace control, including ownership transfer and billing management.
• ADMIN: Manage members and roles (except ownership), plus all editor capabilities.
• EDITOR: Create/edit apps, workflows, and datasets; run workflows and publish changes.
• NORMAL: Read-only access to workspace resources.
• DATASET_OPERATOR: Specialized role managing knowledge bases (datasets) only, without app/workflow access.

Role Validation Methods

Role-checking utilities are statically defined on the TenantAccountRole class, supporting role validation such as:

• is_valid_role(role: str) -> bool
• is_privileged_role(role: Optional[TenantAccountRole]) -> bool
• is_admin_role(role: Optional[TenantAccountRole]) -> bool
• is_editing_role(role: Optional[TenantAccountRole]) -> bool
• is_dataset_edit_role(role: Optional[TenantAccountRole]) -> bool

These methods simplify permission gating throughout the codebase by classifying roles according to capability sets.

Sources: api/models/account.py21-79

---

Tenant-Account Role Association

TenantAccountJoin Model

The many-to-many relationship between users (Account) and tenants (Tenant) is managed via the TenantAccountJoin model, capturing the assigned role per user per tenant. This table is critical for mapping a user's workspace-specific role.

Account Role Management

The Account model caches the current workspace and role for efficient permission checking and sets these via dedicated session-scoped methods. The tenant and role are lazy-loaded or refreshed from TenantAccountJoin entries.

Sources: api/models/account.py21-180 api/controllers/service_api/wraps.py29

---

Enterprise RBAC Integration

Dify integrates an enterprise-tier RBAC system that supports fine-grained resource-level permission controls in addition to the coarse workspace roles.

RBAC Service Architecture

The RBACService in api/services/enterprise/rbac_service.py serves as the API boundary for interacting with enterprise RBAC backends. It defines resource types such as:

• RBACResourceType.APP
• RBACResourceType.DATASET

The service sends requests to internal enterprise APIs (/inner/api/rbac/*) for permission resolution.

Permission Scopes and Keys

Permissions are scoped by resource type and are enforced accordingly:

Scope	Resource Type	Function
APP	RBACResourceType.APP	Controls application lifecycle and configuration access.
DATASET	RBACResourceType.DATASET	Controls dataset/document management.

The system recognizes roles and permission keys via models such as RBACRole, AccessPolicy, and AccessPolicyRoleBinding.

Sources: api/services/enterprise/rbac_service.py44-154 api/controllers/console/wraps.py29-40

---

Validation Wrappers and Security

Dify enforces access control through decorators and wrappers applied to API endpoints, validating tokens, roles, and billing status.

API Token Validation in Service API

The validate_app_token decorator verifies that incoming API requests are authenticated with a valid ApiToken. It confirms the associated app exists and is enabled for API access.

Sources: api/controllers/service_api/wraps.py105-116 api/controllers/service_api/wraps.py120-124

Billing and Quota Checks

The decorator cloud_edition_billing_resource_check integrates RBAC with billing quota enforcement, blocking operations if the user exceeds subscription resource limits such as vector space or member seats.

The check supports multiple resource kinds and integrates with feature flags for granular control.

Sources: api/controllers/console/wraps.py187-202 api/services/billing_service.py207-217

---

Summary of Permission Matrix

Operation	OWNER	ADMIN	EDITOR	NORMAL	DATASET_OPERATOR
App Management	✅	✅	✅	❌	❌
- Create App	✅	✅	✅	❌	❌
- Edit App	✅	✅	✅	❌	❌
Dataset Management	✅	✅	✅	❌	✅
- Create Dataset	✅	✅	✅	❌	✅
- Edit Dataset	✅	✅	✅	❌	✅
Workspace Management
- Member Management	✅	✅	❌	❌	❌
- RBAC Configuration	✅	✅	❌	❌	❌

This matrix summarizes role capabilities with respect to key platform resources.

Sources: api/models/account.py21-79 api/controllers/console/app/app.py33-36 api/services/enterprise/rbac_service.py16

---

Additional Diagrams: Natural Language Space to Code Entity Space

Role Definition to Code Enum

Permission Check Flow in Console API

---

Summary

Dify's Role-Based Access Control system is a layered permission framework that distinguishes user capabilities within a tenant by the TenantAccountRole roles. This system is backed by a many-to-many association table and extended for precision via an enterprise RBAC service that enables resource-level permission policies. The RBAC enforcement is implemented through a combination of static role checks and dynamic enterprise permission queries via internal APIs, guarded by validation decorators that secure both Console and Service API endpoints. Integration with billing further guards against quota violations in resource use.

---

Sources:

• api/models/account.py21-180
• api/services/enterprise/rbac_service.py20-260
• api/controllers/console/wraps.py20-202
• api/controllers/service_api/wraps.py100-125
• api/services/billing_service.py200-220