Role Delegation
Allows site administrators to grant specific roles the authority to assign selected roles to users without requiring the 'administer permissions' permission.
role_delegation
Install
composer require 'drupal/role_delegation:8.x-1.4'
composer require 'drupal/role_delegation:8.x-1.2'
composer require 'drupal/role_delegation:8.x-1.1'
Overview
The Role Delegation module enables fine-grained control over role assignment capabilities. Instead of granting users the powerful 'administer permissions' permission, site administrators can delegate the ability to assign specific roles to designated user roles.
For each role defined in the system, Role Delegation automatically generates a corresponding 'assign [role] role' permission. When a user has one or more of these permissions (or the 'assign all roles' permission), they gain access to role assignment functionality through multiple interfaces: a dedicated 'Roles' tab on user profiles, role checkboxes on the user edit form, and bulk add/remove role operations on the user administration page.
This module is particularly useful for organizations where different administrators need to manage different types of users. For example, a department manager could be given permission to assign 'editor' and 'contributor' roles without having access to assign administrative roles.
Features
- Dynamically generates 'assign [role] role' permission for each role in the system
- Provides a dedicated 'Roles' tab on user profiles (/user/{uid}/roles) for role management
- Adds a 'Roles' entity operation link on the user administration page
- Integrates with the user edit form by adding a role_change field when users have delegation permissions
- Integrates with Views Bulk Operations to filter add/remove role actions based on user's delegation permissions
- Overrides core's AddRoleUser and RemoveRoleUser actions to work without 'administer users' permission
- Automatically revokes 'assign [role] role' permissions from all roles when a role is deleted
- Supports the single_user_role module by handling both checkbox and radio button inputs
Use Cases
Department-based role management
A large organization has multiple departments, each with their own 'department editor' role. Department managers need to assign editor roles to their team members but should not have access to administrative roles. Grant each manager the 'assign [department]_editor role' permission, allowing them to manage their team's access without compromising site security.
Content moderation delegation
An editorial workflow requires senior editors to promote users to 'reviewer' or 'publisher' roles. Instead of giving senior editors full permission administration rights, grant them 'assign reviewer role' and 'assign publisher role' permissions. They can manage the content team hierarchy while being restricted from accessing technical or administrative roles.
User onboarding by HR
HR staff need to set up new employee accounts with appropriate roles based on their department and job function. Grant HR users 'assign all roles' or specific department role permissions. They can complete user setup through the Roles tab without needing access to other administrative areas.
Self-service role requests
Combined with a request/approval workflow module, users could request certain roles that a manager then approves. The manager only needs the delegation permission for those specific roles to complete the approval by visiting the user's Roles tab.
Temporary access elevation
Support staff occasionally need elevated permissions to assist users. A team lead with 'assign support_admin role' permission can temporarily grant and later revoke this role from team members as needed, without involving full site administrators.
Tips
- Grant 'assign all roles' sparingly - it provides the same role assignment power as 'administer permissions' without the ability to change permission settings
- The Roles tab appears in user profiles only for users who have delegation permissions and do not have 'administer users' permission
- Role delegation works with Views Bulk Operations, making it efficient to assign roles to multiple users at once from /admin/people
- When a role is deleted, all 'assign [role] role' permissions are automatically revoked from other roles
- The module adds a 'Roles' operation link to the user admin page dropdown menu for quick access to role management
Technical Details
Admin Pages 1
/user/{user}/roles
A dedicated form for managing role assignments for a specific user. This page displays checkboxes for each role that the current user has permission to assign. Users can check or uncheck roles and save to update the target user's role assignments. This page is only accessible to users who have at least one 'assign [role] role' permission or the 'assign all roles' permission, and who do not have the 'administer users' permission (as those users should use the standard user edit form).
Permissions 2
Hooks 12
hook_help
Provides help text for the module on the help page.
hook_user_role_delete
Cleans up 'assign [role] role' permissions when a role is deleted. Finds all roles that have the permission to assign the deleted role and revokes that permission.
hook_user_presave
Processes role changes submitted through the role_change field. Adds roles that were checked and removes roles that were unchecked, but only for roles the current user has permission to assign.
hook_user_load
Sets the empty field value marker on the role_change computed field when users are loaded. This allows distinguishing between intentional role removals and missing field data.
hook_form_user_form_alter
Modifies the user form to place the role_change field in the account group and adds an entity builder to handle cases where the field is not accessible.
hook_field_widget_single_element_form_alter
Sets the default value for the role_change widget based on the user's current roles, since computed fields don't store values.
hook_options_list_alter
Filters the options for the role_change entity reference field to only show roles the current user can assign.
hook_entity_base_field_info
Adds the 'role_change' computed base field to user entities. This field uses entity reference to user_role with options_buttons widget.
hook_entity_field_access
Controls edit access to the role_change field. Denies access if user has 'administer permissions' (should use normal roles field). Allows access if user has any role delegation permission.
hook_entity_operation
Adds a 'Roles' operation link to user entities on the admin/people page, linking to /user/{uid}/roles.
hook_views_data_alter
Overrides the user_bulk_form Views field plugin with role_delegation_user_bulk_form to filter bulk operations based on delegation permissions.
hook_action_info_alter
Replaces core's AddRoleUser and RemoveRoleUser action classes with role delegation versions that work without 'administer users' permission.
Troubleshooting 5
This is expected behavior. Users with 'administer users' permission should use the standard user edit form which includes the full roles field. The Roles tab is designed for users who can delegate roles but cannot fully administer users.
This is expected behavior. Users with 'administer permissions' have access to the standard roles field on the user edit form. The role_change field is hidden for these users to avoid duplicate role selection interfaces.
Ensure the user has at least one 'assign [role] role' permission or 'assign all roles' permission. The bulk form field filters actions based on these permissions.
Verify the user has the specific permission for the role being assigned. The module only processes role changes for roles the current user has permission to delegate, silently ignoring unauthorized changes.
The module automatically revokes 'assign [role] role' permissions when a role is deleted via hook_user_role_delete. If permissions persist, clear the cache with drush cr.
Security Notes 5
- The 'assign all roles' permission is marked as 'restrict access: TRUE' because it allows assigning any role including administrative ones
- Users cannot assign roles they don't have explicit permission to delegate - the module validates all role changes against current user permissions
- The module prevents users with 'administer permissions' from using the role_change field to avoid bypassing the standard permissions interface
- Role delegation permissions do not grant the ability to create, delete, or modify role definitions - only to assign existing roles to users
- When roles are deleted, associated delegation permissions are automatically cleaned up to prevent orphaned permission references