Multi-Tenant Context Propagation#

Dify enforces tenant isolation through two complementary mechanisms that run in parallel during every app execution:

1. DifyRunContext — a structured identity object threaded explicitly through the workflow graph, child engines, and node runtime classes.
2. FileAccessScope — a Python ContextVar scoped to each app execution that gates all database lookups for UploadFile and ToolFile records.

Both were progressively hardened across a series of refactors (primarily PR #32964, PR #39042, PR #39149, and PR #34044) that replaced implicit tenant/user derivation from session/user objects with explicit parameter passing.

DifyRunContext — Identity Carrier#

DifyRunContext is a Pydantic model with eight fields:

build_dify_run_context() is the single factory. It wraps the model in a dict[str, Any] under the reserved key "_dify" (DIFY_RUN_CONTEXT_KEY), allowing callers to attach additional context keys without clobbering the identity payload.

InvokeFrom.runs_as_account() is the canonical check for whether a run is attributed to a workspace Account (DEBUGGER, EXPLORE) vs. an end user (WEB_APP, SERVICE_API, TRIGGER). This drives UserFrom resolution in all app runners 1.

Propagation Through Workflow Execution#

AppGenerator
  └─ build_dify_run_context(tenant_id, app_id, user_id, ...)
       └─ DifyGraphInitContext → DifyNodeFactory → Graph
                                                         └─ child engines (iteration/loop)
                                                              └─ same run_context via _WorkflowChildEngineBuilder

Graph initialization: WorkflowBasedAppRunner._init_graph() calls build_dify_run_context() and wraps the result in DifyGraphInitContext, which bridges the identity payload into graphon's GraphInitParams. DifyNodeFactory.from_graph_init_context() then creates all graph nodes within that scoped context 2.

Child engines: Iteration and loop nodes spawn independent child GraphEngine instances via _WorkflowChildEngineBuilder. These inherit the parent's run_context directly — no re-construction needed — so tenant_id and user_id flow automatically to all subgraph nodes 3.

Single-node debug runs: _get_graph_and_variable_pool_for_single_node_run() builds its own run_context from workflow.tenant_id and an explicit user_id argument 4. Before PR #34044, this path hardcoded user_id="", causing DatasetQuery.created_by to fail UUID validation in PostgreSQL inside iteration subgraphs. The fix threads the real user_id from application_generate_entity through _prepare_single_node_execution() into this method.

Context Resolution in Node Runtime#

Nodes access identity via resolve_dify_run_context(run_context) in node_runtime.py, which normalizes both raw Mapping and DifyRunContext inputs by keying on DIFY_RUN_CONTEXT_KEY. It raises ValueError if the key is absent, making missing context a hard failure rather than a silent bug.

Two key runtime classes use the resolved context for tenant/user scoping:

• DifyFileReferenceFactory — passes run_context.tenant_id to file_factory.build_from_mapping(), ensuring every file reference resolves within the correct tenant's storage 5.
• DifyToolFileManager — passes both run_context.user_id and run_context.tenant_id to ToolFileManager.create_file_by_raw(), attributing created tool files to the correct user and tenant 5.

Repository Tenant Isolation#

PR #39042 refactored all workflow execution and node execution repositories to accept tenant_id as an explicit constructor argument rather than deriving it from user objects.

DifyCoreRepositoryFactory exposes two factory methods — create_workflow_execution_repository() and create_workflow_node_execution_repository() — both requiring tenant_id: str alongside user, app_id, and triggered_from. The factory dynamically loads the configured repository implementation via import_string() and forwards tenant_id to it.

All app generators (workflow, advanced chat, pipeline) call these factories with tenant_id=app_model.tenant_id, so the tenant boundary is set from the app model at execution start and never re-derived from session state downstream.

File Access Tenant Scoping#

File lookups use a separate ContextVar-based mechanism. FileAccessScope is a frozen dataclass bound per execution via bind_file_access_scope(). It carries tenant_id as a mandatory outer boundary: DatabaseFileAccessController unconditionally appends UploadFile.tenant_id == scope.tenant_id to every SQL query, with additional user_id ownership filters for end-user contexts.

BaseAppGenerator._bind_file_access_scope() constructs the initial scope from tenant_id, user, and invoke_from at the start of every app execution. All app types — completion, chat, agent, advanced chat, workflow — pass through this base method.

Trial app cross-tenant fix (PR #39149): When a user explores another tenant's shared trial app, the upload API was previously creating files under the exploring user's own tenant. The fix added TrialAppFileUploadApi and TrialAppRemoteFileUploadApi endpoints at /trial-apps/<app_id>/files/upload that pass resource_tenant_id=app_model.tenant_id explicitly to FileService.upload_file(), ensuring uploaded files are owned by the app's tenant rather than the requesting user's tenant.

Key Files and References#

Notable PRs: