Custom RBAC Roles (Pro)

DefectDojo Pro feature. The Members / Groups / Global Roles RBAC system described on this page is part of DefectDojo Pro. Open-source DefectDojo uses the Authorized Users model. See that page for open-source access control, and the 3.0 upgrade notes if you’re moving between editions.

DefectDojo Pro ships five roles: Reader, Writer, Maintainer, Owner, and API Importer. If none of them is the right fit, you can now build your own role by choosing exactly which permissions it grants.

A custom role works anywhere a built-in role works: as a Global Role, as a Group’s role, as the default group role, and as a member role on an individual Organization or Asset.

The five built-in roles become locked, clonable presets. Their permissions are unchanged (see the Action permission charts for what each one grants), they cannot be edited or deleted, and cloning one is the recommended way to start a new role.

Before you start#

Custom role management is off by default. A superuser turns it on from Settings > Feature Flags, by enabling Custom Roles. See Feature Flags for how that page works.

While the feature is off, the Roles page is still readable: you can view the built-in roles and their permissions, but you cannot create, edit, clone, or delete anything.

Managing roles requires superuser status or the built-in Owner Global Role. This is deliberate and cannot be delegated to a custom role: see What a custom Global Role unlocks.

Opening the Roles page#

Go to 👤 Users > Roles in the left sidebar. The menu entry is visible to superusers and holders of the built-in Owner Global Role.

The table lists every role in your instance:

Every column is sortable and filterable, and the keyword search matches on name and description.

Creating a role#

Clone a built-in role (recommended)#

Cloning starts you from a known-good permission set instead of an empty grid, which makes it much harder to accidentally leave out a permission a role needs.

1. Find the role closest to what you want.
2. Open its ⋮ menu and choose Clone Role.
3. A copy is created immediately, named <original> (copy), with the same permissions and description as the role it came from.
4. Open the copy’s ⋮ menu, choose Edit Role, then rename it and adjust its permissions.

Built-in roles can be cloned even though they cannot be edited. The clone records which role it came from.

Start from scratch#

1. Click New Role.
2. Give it a Name (required) and optionally a Description.
3. Choose its permissions in the grid below (see the next section).
4. Click Save Role.

Role names must be unique, and the check ignores case: if Triage Lead exists, triage lead is rejected.

Choosing permissions#

Permissions are grouped into three tables plus a checklist.

Object Permissions apply to the Organizations and Assets the role is assigned to, and to everything nested under them.

1. Asset > Add means creating a new Asset inside an Organization the role is assigned to.
2. View for Notes and Benchmarks is inherited: a role that can view the parent Engagement, Test, Finding, or Asset can view its Notes and Benchmarks. These cells show a ? icon instead of a checkbox.

Group & Member Permissions control who can manage membership. The columns here are View, Manage, Add, Add Owner, Edit, and Delete.

Global Feature Permissions gate instance-wide Pro features rather than individual Organizations or Assets, so they only take effect when the role is held as a Global Role. Granting them on a role that is only used as an Asset membership has no effect.

Additional Permissions is a checklist of capabilities that don’t fit a View/Add/Edit/Delete shape:

• Configure Asset Notifications: choose which notifications a single Asset sends, and where.
• Import Scan Result: import and re-import scan results, creating and updating findings.
• Share Dashboard Layout: publish a dashboard layout to other users. Global Role only.
• Share Table Preference: publish a saved table view (columns, filters, sort order). Global Role only.
• View Note History: see who changed a note and when.

How to read the grid#

In each row, the leftmost permission (View, or Manage on member rows) gates the rest of the row. You have to grant it before the other cells in that row become available, because a role cannot meaningfully edit or delete what it cannot see. Clearing the gate clears the rest of the row with it.

Editing, cloning, and deleting#

Each row’s ⋮ menu offers Edit Role, Clone Role, Delete Role, and Role History.

Built-in roles only offer Clone Role. They cannot be edited or deleted, by anyone, including superusers. This keeps a known baseline in place and keeps upgrades predictable.

Deleting a role that is still assigned to anyone will fail. Reassign or remove those assignments first, then delete the role. Assignments that count for this purpose are Organization and Asset memberships (both user and group), Global Roles, Group memberships, and the default group role in System Settings.

The API can do the reassignment for you in a single call. See Managing roles through the API.

Assigning a custom role#

Custom roles appear in every role dropdown, alongside the built-ins:

Two constraints are worth knowing:

• Owner-tier is reserved. A custom role can never be an owner-tier role. Only the built-in Owner is, so only it carries the implicit power to manage other Owners.
• Granting the Owner role to someone else still requires the matching Add Owner permission, whether you do it on an Organization, an Asset, or a Group.

What a custom Global Role unlocks#

Parts of the UI are gated on a minimum Global Role rather than on an individual permission. To make custom roles work with those gates, DefectDojo ranks a custom Global Role against the built-in tiers: a custom role earns the highest tier whose permissions it completely covers.

• A custom role that covers everything Maintainer grants is treated as Maintainer for those gates.
• Cover everything Writer grants, and it is treated as Writer. Same for Reader.
• Cover none of them completely, and it earns no tier. Its individual permissions still work exactly as granted; only the tier-based UI gates stay closed.
• Owner can never be earned this way. Role management, and everything else gated on the Owner Global Role, stays with superusers and the built-in Owner.

Coverage has to be complete, which occasionally surprises people. A role cloned from Maintainer earns the Maintainer tier. Rebuild Maintainer’s permissions by hand, miss one, and the role lands on the Writer tier instead. If a custom Global Role is missing UI you expected, compare it against the built-in tier in the Action permission charts.

Role history#

Custom roles keep an audit trail. Open Role History from a role’s ⋮ menu to see which permissions were granted or revoked, by whom, and when, alongside changes to who holds the role.

Two things this history does not show: changes to a role’s own name and description, and the permissions of built-in roles (those are seeded, never edited, and so never generate history).

Role history is a read, so it is available whether or not the Custom Roles feature is on.

Managing roles through the API#

Roles are available at /api/v2/roles/. Reads are open to any authenticated user, because clients need the role list to populate dropdowns. Writes require superuser status or the built-in Owner Global Role, plus the Custom Roles feature flag.

Notes:

• permissions replaces the role’s grant list rather than adding to it. Send the full set you want the role to end up with.
• ?reassign_to= moves every assignment of the deleted role to the role you name, in one transaction. This is the only way to reassign in bulk: the UI does not offer it.
• Attempting to edit or delete a built-in role returns 403. Editing an unknown permission value, reusing an existing role name, or deleting an in-use role without reassign_to returns 400 with an explanation.
• is_owner cannot be set through the API. Posting it is accepted and ignored.

Things to know#

• Multiple roles on the same object grant the union of their permissions. If a user holds a role directly on an Asset and inherits another through a group, they get everything either role grants. Roles only ever add permissions, never remove them.
• Permission changes are picked up on the next page load, not instantly in the current view. Background jobs may take up to 30 seconds, and cached permission data up to 5 minutes, to reflect an edit.
• Role dropdowns list up to 250 roles. Beyond that, some roles will not appear in dropdowns, though they continue to work.
• Maintainer and Owner can add Organizations, but the grid does not show it. For those two roles that grant is stored as a global-scope grant, and the grid reads only object-scope grants, so their Organization > Add cell reads as not granted. Cloning either role preserves the grant.
• Terminology follows your instance. These docs use Organization and Asset, the default labels. If your instance has turned Organization / Asset relabeling off, the same rows read Product Type and Product instead.
• The Roles page is read-only for everyone else. A user who reaches /settings/roles directly can see the roles and their permissions but cannot change anything. Permission data is not sensitive, and the server enforces the real boundary on every write.