Dify Enterprise custom roles and permission templates

Dify Enterprise custom roles and permission templates: when a default role model stops fitting

A default role model stops fitting once several teams share Dify Enterprise workspaces and the people who build apps, release them and grant access are no longer the same people. Custom roles and permission templates let you define those rights once and apply them consistently to each new workspace, with per-app exceptions where a team genuinely needs more or less. Dify Enterprise is the edition that adds SSO and multiple workspaces, according to the Dify pricing page, so this design work matters only once you are running more than the single workspace the Community edition allows. Before you design anything, confirm in the product which built-in role names exist, which permissions each role carries, and whether custom roles and reusable templates are offered in your Enterprise version. Role names and permission lists change between releases, so record them from your own instance rather than from memory or documentation written for another version.

Start by separating three duties that are often bundled into one admin role: building apps, deploying or publishing them, and granting other people access to them. Builders need edit rights on draft apps and their knowledge bases. Release owners need the ability to publish and to control which version users see. Access administrators need to change who can use a published web app. Map each duty to the exact permissions the product exposes, then decide which combinations a single person should never hold. For example, a team that can both publish an app and widen its access level has a path to exposing internal data without review. Write this as a permission matrix in your change record, with one column per duty and one row per permission, so reviewers can check it against the product before you create the template.

Permission templates then become the place where your decisions are repeated. Create one template per workspace type, such as a sandbox for experiments and a production workspace for customer-facing apps, and keep per-app exceptions few and documented with an owner and an expiry date. Test each template in a non-production workspace, sign in as a user holding each role, and attempt the actions the matrix says should fail. Record the results, because a role that looks correct in the console can still allow an action you did not plan for. Ask your DeployOpen or Dify contact to confirm, in writing, how a template applies to workspaces created after it is defined and whether changes propagate to existing apps.

How to split builders, deployers and access granters

The builder role covers the work of creating and editing workflows, agents, prompts and knowledge base content inside a workspace. Builders need enough access to iterate on app configuration and test it, but the design should keep them away from publishing to end users and from changing who can see an app. In a regulated setting, this is the group most likely to touch prompts, data sources and model choices, so their rights should be narrower than the people who own those decisions.

Editing app logic: Builders can create and modify workflows, prompts and tool settings in apps assigned to them.
Knowledge base work: Builders can add or update documents in knowledge bases they are approved to use, without rights to create new connections to external data sources.
Testing: Builders can run drafts in the preview panel for their own testing.
Not publishing: Builders should not hold the right to publish a version to a production web app or API.
Not granting access: Builders should not manage member lists, groups or web app access levels.

Before assigning this role, confirm in the Enterprise console which permissions are exposed for app editing and knowledge base management, since the exact names come from the product and must be verified there.

Permission template options and when each fits

This table compares four ways to structure workspace roles and app permissions in Dify Enterprise: default roles only, one custom role per team, a template per workspace type, and per-app exceptions. Read each row for the admin effort it creates, the audit burden it adds and the failure mode operators most often hit. The main takeaway is that templates scale better than ad hoc exceptions, and that exceptions should stay few and documented.

Template option	Admin effort and audit burden	Typical failure mode and when it fits
Default roles only	Lowest setup effort. Audit is simple because role meanings are fixed, but reviewers must still check each member's workspace role by hand.	Builders and publishers end up sharing rights they do not need. Fits a small pilot with one trusted group and a short list of apps.
One custom role per team	Moderate effort to define and name each role. Audit grows with team count, and every new team needs its own role review.	Roles multiply and drift apart, so two teams with similar work hold different rights for no clear reason. Fits organizations with stable, distinct teams that own their apps.
Template per workspace type (sandbox, staging, production)	Higher upfront design effort, then lower change effort because new workspaces inherit the template. Audit focuses on a few templates and their approved changes.	Production templates get loosened to unblock a deadline and the change is never reversed. Fits regulated teams that need separate build, test and release rights per environment.
Per-app exceptions	Effort is small for one app but compounds across many apps. Audit requires listing every exception with an owner and reason.	Exceptions are granted informally and outlive the project, so nobody can say who can edit a live app. Fits a narrow, time-limited need that the templates cannot cover.
Separation of build, deploy and access grants	Requires defining who may build, who may publish and who may grant web app access as distinct permissions. Audit can trace each step if roles are split this way.	A single admin holds all three rights and nobody reviews changes. Confirm in your Dify Enterprise version which permissions can be separated before you commit to this design.

Setting up workspace roles and templates in order

This sequence produces a tested permission template for new workspaces and a short, approved list of per-app exceptions. Each step ends with a check that keeps build, publish and access-granting duties separate before the template reaches production. Work through the steps in order, because exceptions only make sense against a template that has already been tested.

Inventory who performs each function
Start by listing every task that touches an app in the workspace: building workflows and prompts, editing knowledge bases, publishing, changing web app access, viewing logs and managing members. Ask team leads who currently performs each task and who approves it. Have the leads confirm the list, then record it as one table of functions and current holders. This step is done when every function has a named owner and no task appears without one.
Map functions to workspace roles
Map each function to a workspace role, keeping building, publishing and access-granting in separate roles where your policy requires it. Begin with the built-in roles in your Dify Enterprise version, and confirm the exact role names and permission settings in your own console before you document anything, because they can change between releases. Where one person needs two functions, record the conflict and decide whether your policy allows it. This step is done when every function maps to one role and each conflict has a written decision.
Write the workspace permission template
Write the permission template that new workspaces start from. Set the workspace role for each group, the default access for resources created in the workspace, and who may change web app access levels. Keep the template short enough that a workspace administrator can explain it in one meeting. Save it as a written specification that lists role names, settings, the approver and the approval date, then create a test workspace from it. This step is done when the test workspace matches the specification without manual edits.
Test the template with pilot users
Test the template with one pilot user for each role. Each pilot signs in through the identity setup your organization uses, then checks what the role can and cannot do. A builder should be able to edit workflows and prompts but should be unable to change web app access levels. A granter should be able to manage who uses an app but should be unable to open or edit its workflow. Confirm that group members see only the workspaces and apps intended for them, and log every result. This step is done when each check passes or each gap has a logged fix and a successful retest.
Add per-app exceptions last
Add per-app exceptions only after the template passes testing. An exception is a resource-level permission that differs from the workspace default, such as one builder allowed to edit a single sensitive app or one group given access to a single published app. Keep the list short, and where the same exception applies to several people, check whether a group membership change achieves the same result more clearly. This step is done when each exception is listed with its app, the person or group affected, and the permission it changes.
Record approval for each exception
Record an approval for each exception before it takes effect. The approver should hold neither the permission being granted nor the role that requested it, such as the workspace owner or a security lead, so no one approves their own access. Store each approval with the request, the business reason, the review date you set and the person who applied the change. After each change, rerun the pilot checks for the affected app. This step is done when every live exception has an approval record and a review date that you can show an auditor.

Security risks of loose role design in Dify

Role design in Dify decides who can build, publish, share and grant access to apps. The risks below tend to appear together, so each card pairs a failure mode with the control that limits it. Confirm how SSO and SCIM interact with custom roles in the Enterprise documentation before you rely on any of them.

Builders who can also publish

When one role lets a person edit a workflow, change its prompts and push it to production, a single account can alter what users see without a second review. Separate the build role from the deploy role, and decide which role owns the publish action for each environment. Ask the vendor which permissions in the custom role model control publishing and whether a publish can be restricted without also blocking editing.

Broad app exceptions that outlive their purpose

A per-app exception granted for a pilot, a contractor or a one-time migration often stays long after the reason has gone. Each exception should have a named owner, a stated purpose and a review date. Record the app, the grantee and the permission in a register, and remove the exception when the project closes rather than leaving it in place by default.

Role drift after team changes

Roles that were correct at setup tend to accumulate permissions as people move between projects and no one removes the old ones. Compare current role assignments with the current org chart at a fixed interval, and treat any member who holds build, publish and grant rights together as a finding. Confirm whether SCIM group changes update workspace roles automatically or only create accounts, since that determines where drift starts.

Access granted outside the audit trail

Access granted by a direct invitation, a shared link or a manual change in the console can bypass the group structure your reviewers look at. Require that every grant follows a documented path, such as a group membership change tied to a ticket. Confirm which administrative actions Dify Enterprise records, how long those records are kept and whether they can be exported to your log platform.

Grants that depend on one administrator

If a single workspace owner is the only person who can grant or revoke access, a departure or a compromised account stalls both onboarding and offboarding. Assign at least two administrators with the grant right, keep their accounts under your identity provider's controls, and document a break-glass procedure. Confirm in the Enterprise docs how workspace owner rights transfer when the owner's account is disabled.

How the role and permission model fits with SSO and SCIM

Identity provider groups and SCIM provisioning decide who enters a workspace, while Dify roles decide what those people can do once inside. Keep these two layers separate in your design. Your identity provider, whether Microsoft Entra ID, Okta or another SAML or OIDC source, controls account creation, group membership and deprovisioning through the Dify Enterprise SSO documentation. The workspace permission set you define in Dify then determines whether a member can build, publish, manage the knowledge base or grant access to apps. A user who leaves the identity provider should lose access on the next sync, so your offboarding process depends on SCIM working correctly, not on remembering to edit roles by hand.

The risk sits in the mapping between an identity provider group and a Dify role. If a broad group such as an all-engineering or contractor group is mapped to a role that can edit apps, manage members or change access settings, every future member of that group inherits those rights automatically. A safer pattern is to map narrow groups to build-only or operate-only permission sets and keep access-granting rights with a small administrative group. Confirm the exact behavior with your installed version: whether group-to-role mapping is supported at all, whether it applies at sign-in or during sync, what happens when a user belongs to several groups, and whether a role change takes effect for existing sessions. Record these answers in your design document before you assign any group.

Test the mapping in a staging workspace before production. Create one test account per group, sign in through the identity provider, and confirm the workspace roles and app permissions that result. Then remove the test user from the group, run a sync, and confirm access drops as expected. Repeat this check after each Dify upgrade, because SSO and SCIM behavior can change between releases. Ask your Dify contact, and read the release notes for your target version, to confirm how role attributes from the provider are handled, since the mapping rules are the part of this design most likely to differ from what your team assumes.

Limits to confirm in your Dify Enterprise environment

Several details that shape a permission template cannot be settled from general documentation alone. The cards below list what to confirm in your own Dify Enterprise environment before you write the templates, and each check should be repeated after every minor release.

Exact built-in roles

Start by listing the roles your Dify Enterprise version ships with, including their names, their default permissions and whether each one can be edited or only copied. Template design depends on this list, because a custom role is only useful if you know which built-in role it replaces or sits beside. Record the list with a screenshot or export from the admin console so you can compare it after an upgrade. Ask your vendor contact to confirm the role set for the exact version you run.

Resource coverage of custom roles

Check whether a custom role can grant or withhold permissions for every resource type in the workspace, such as apps, knowledge bases, plugins, model providers, logs and members. A gap means some resources fall back to a default behavior that may be broader than you intended. Build a test matrix with one test user per role and attempt each action against each resource type. Treat any resource type you cannot control as an open risk in the template.

Exceptions and workspace defaults

Confirm how a per-app exception interacts with the workspace default. Find out whether an exception can only widen access, whether it can also narrow it, and which setting wins when a user holds two roles through group membership. Test this with a group that has a restrictive role and a direct grant on one app, then record the effective access. Without this check, an exception granted for one project can quietly expose apps that were meant to stay private.

Limits on roles and workspaces

Ask for the documented maximum number of custom roles, workspaces and members per workspace in your edition, and whether any of these limits differ between Enterprise deployments and managed environments. Limits affect how far you can split builders, deployers and approvers into separate workspaces. Confirm the limits in writing before you design a workspace per team, because restructuring later means moving apps and re-granting access.

Behavior across minor releases

Dify minor releases arrive roughly monthly, so a permission model that works today may change after an upgrade. Ask whether custom role definitions, exceptions and group mappings survive minor upgrades without manual edits, and which release notes describe permission changes. Keep a regression test set of your role matrix and run it against a staging instance before each production upgrade. Take a backup before every upgrade as the Docker Compose upgrade guidance recommends.

Admin audit visibility

Confirm which role changes, exception grants and group mapping edits are written to an audit trail, who can read that trail and how long entries are kept. Permission templates are only as trustworthy as your evidence that they were applied as designed. Ask for a sample audit record for a role change and an exception grant, and check whether the record shows the actor, the target and the previous value.

Questions buyers ask before designing Dify roles

How much effort does a Dify role design take?

Effort rises with the number of teams, workspaces, apps and exceptions that need their own access rules. The work has three parts: mapping who builds, deploys and grants access, writing a permission set for each role, and testing those sets against real accounts. The design is a one-time cost, but reviews and changes recur as teams and apps change. Your own staff time is a cost even when a partner does the design, because someone must make the access decisions and approve them. A written scope should separate the design, the pilot and the handover so you can see what each phase delivers. Ask the provider which parts of the effort depend on your identity provider groups and which depend on your app count.

Can an internal team design Dify roles without a partner?

Yes, a team with Dify administration experience and an owner for your identity provider can design roles in-house. The difficult part is rarely the console settings. It is agreeing on who may build, who may publish and who may grant access, and then proving that each role behaves as intended. Internal teams often underestimate the testing step, which needs test accounts in each role and a record of what each account can see and change. A partner adds value when the scope is large, when several business owners disagree on access, or when your staff cannot spare time for a multi-week design. Whichever path you choose, keep ownership of the final role matrix inside your organization.

What inputs does a Dify role design project need from us?

The project needs a clear set of inputs before design starts:

A role inventory listing current users, their duties and the workspaces they use today.
A named approver for each workspace who can accept or reject access requests.
An app inventory with an owner, a sensitivity level and a note on whether the app serves internal staff or external users.
Identity provider groups for build, deploy and governance duties, if you plan to map them through Enterprise SSO.
Pilot users from each duty group who can test the roles before rollout.

Missing inputs cause the most rework. If approvers are unnamed, the access model stalls. If pilot users are unavailable, errors surface after rollout instead of during testing. Ask for this list in writing before you accept a quote.

How long does designing Dify roles take?

The duration depends mainly on the number of teams and apps, and on how many of those apps need exceptions to the standard role set. A small organization with a few workspaces and a shared app pattern needs far less time than one with many business units, each with its own publishing and approval rules. Delays usually come from unresolved ownership, waiting for approvers, and pilot cycles that repeat because the first test exposed a gap. We do not publish a fixed timeline for this work. A sound quote will state the phases, the dependencies on your staff and the assumptions behind the schedule, so you can check each one against your own calendar.

Do custom roles in Dify require the Enterprise edition?

Confirm this with Dify before you commit, because the supplied pricing information does not settle it for custom roles specifically. The pricing page describes the self-hosted Community edition as free and limited to a single workspace, while the Enterprise edition adds SSO, multiple workspaces, advanced security, a commercial license and professional support. Since the design of separate workspaces and identity-linked access depends on those Enterprise features, plan on Enterprise if you need several workspaces or SSO-based access. You can review the current edition comparison on the Dify pricing page. Ask the vendor to confirm in writing which role and permission features are included in the version you plan to run.

How should we review Dify role exceptions over time?

Record every exception with its owner, the business reason, the app it affects and an expiry or review date. Review the register on a fixed schedule, such as each quarter, and remove exceptions whose project has ended. Pair the review with your identity provider lifecycle, so that leavers and movers lose access through SCIM deprovisioning or your normal offboarding process rather than through manual cleanup in the console. Check the role matrix after each Dify minor release, because releases arrive roughly monthly and may change console behavior. Keep the register and the review record as evidence of who approved each exception and when it was last confirmed.

What should a Dify role design quote include?

A useful quote lists the scope in phases: discovery and role inventory, role and permission set design, exception handling for named apps, pilot testing, rollout support and handover documentation. It should name the deliverables for each phase, such as the role matrix, the exception register and a test record. It should state what you must provide, including the inputs listed above, and which assumptions the schedule depends on. Ask whether post-handover review is included or offered as a separate retainer. Fixed-scope agreements set scope, deliverables and timelines in writing before work starts, so compare each quote against that same list of phases. Ask for a clear statement of what happens if the scope grows during the pilot.

How DeployOpen scopes and delivers Dify role design

DeployOpen plans Dify Enterprise custom roles and permission templates as part of a self-hosted deployment inside your own infrastructure, starting from who builds, who deploys and who grants access. We agree the role model, per-app exceptions and handover in writing before the build starts, so your team can review and operate what we deliver.

How we scope

Engagements are fixed-scope, with the role catalog, permission sets and per-app exceptions agreed in writing before work starts.
We map builders, publishers and access administrators to the workspaces they will use, and confirm which sign-in scopes apply.
We confirm with you which Dify Enterprise features and license terms your edition includes before we commit to a role design.

How we build

We configure custom roles and default permission templates for new workspaces in a staging environment first.
We test each role against sample build, deploy and access-grant tasks, recording which accounts can perform which actions.
We document the permission matrix, exception register and change steps so role edits follow a repeatable review process.

How we hand over

You receive the role matrix, template definitions, exception list and test results as written deliverables.
We walk your administrators through how to create workspaces from templates and how to request a new per-app exception.
We agree in writing which access reviews your team runs on a recurring basis and which items stay with DeployOpen.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer, covering role changes after Dify releases.
We re-run the role tests after each planned upgrade and report any permission changes that need your approval.
Ask us to confirm support scope, response expectations and retainer terms in the written quote before you commit.

Dify Enterprise custom roles and permission templates