README

A subrole is a set of extra permissions that belongs to a parent role. Users keep their role, which is what views, blocks and themes check, and subroles only add permissions while they have it.

Example: the editor role with the publisher and reports subroles.

Requirements

Drupal ^11.2 (core user module only, no contributed dependencies).
PHP 8.3 or later.

Installation

Place the module in modules/custom/subroles and enable it:

drush en subroles

Configuration

Give the administer subroles permission to the people who will manage subroles.
Go to /admin/people/subroles and add a subrole to a role.
Choose its permissions in the "Permissions" tab.
Edit the user form display (/admin/config/people/accounts/form-display) and place the "Subroles" field where you want it.
Give the assign {subrole} subrole permission to who may assign it.

How it works

subrole config entity: id, label, role (parent role), description, permissions. It depends on user.role.{role}, so deleting the role deletes its subroles. Permissions of uninstalled modules are removed.
user.subrole base field: multi-value reference, created and removed by Drupal's module installer.
SubrolesAccessPolicy: adds the permissions of the subroles whose parent role the user has. It never removes permissions.
Consistency: a subrole without its parent role has no effect, and is removed from the user on save (hook_user_presave). In the user form it is dropped when its role is unchecked. For an existing account, adding a subrole through JSON:API or REST without its role is a validation error.
User form: each subrole is only shown if its parent role is checked (#states), and the whole field is hidden while none of them can be shown. If the "Subroles" field comes right after "account" in the form display (or in its Field Group group), each subrole appears indented below its role. Subroles whose role has no checkbox stay in their own field. The field always uses check boxes: other widgets can't be chosen in the form display, and one saved in config is ignored.
Order: drag the subroles in the list, in the table of their role, to set their order in the user form (weight property).

Permissions

To manage subroles:

administer subroles: create and edit subroles and their permissions. It can give extra permissions to any role, so treat it like administer permissions.

To assign them:

assign {subrole} subrole: give or remove that subrole on other users you can edit. There is one permission per subrole, listed with the role it belongs to.
assign subroles: the same for every subrole. It can give users permissions you do not have.
assign own subroles: change your own subroles. By default, only administrator roles have it.
administer permissions allows all of the above.

If you cannot edit a user, you cannot change their subroles. In the user form you only see the subroles you can assign, and the others stay as they were. Forms, JSON:API and REST all check this through the SubroleAssignment constraint. Code that saves a user without validating it is not checked.

To see them:

view own subroles: the subroles of your own account.
view subroles of other users: the subroles of users whose profile you can view, in lists and through the API too. It includes your own.
administer subroles allows both.

Without these, the field stays hidden, even with administer users.

A subrole never grants administer permissions, administer subroles, manage restricted subrole permissions or any permission to assign subroles. Those can only be given through a role.

Restricted permissions

A restricted permission is one marked as for trusted roles only. To add one to a subrole, or to give or remove a subrole that includes one, you must have that permission yourself. Otherwise, you need manage restricted subrole permissions or administer permissions. This also applies to assign subroles.

In the permissions of a subrole, the ones you cannot change are disabled and stay as they were. The list of subroles shows how many each one includes, and how many users have it.

Audit log

The subroles log channel records who gives or removes a subrole, and who changes the permissions of a subrole or deletes it. It only stores IDs.

Deleting a subrole

It is removed from all users, and its assign {subrole} subrole permission from all roles. Another subrole created later with the same ID starts from scratch.

Recommended modules

Role Hierarchy is optional. It stops users from editing anyone above them and, with "Strict hierarchy check", anyone at their level. Subroles follows those rules.

If you use several user form modes (for example, with Multiple Registration), enable the "Subroles" field in each one.

UI

/admin/people/subroles: one table per role, each with a link to add a subrole to it (?role=ID filters them). Each role in /admin/people/roles has a "Subroles" operation.
/admin/people/subroles/manage/{subrole}/permissions: permissions matrix. Permissions already given by the parent role are checked and disabled.

Views

"Subroles" filter (User table): select list of the available subroles. It is removed from the view for users without administer subroles or view subroles of other users, because filtering shows who has each subrole.
"Subroles" field: entity reference "Label" formatter. It follows the view permissions above.
Access to a view: use the Permission plugin, not Role. Subroles grant permissions, so no extra integration is needed.

Translations

Source strings are in English. translations/es.po is imported automatically by locale (drush locale:check && drush locale:update), wherever the module is installed.

Extending the user form

When a form has no role selector but already knows the role a new user will have, add it to $form['subrole']['widget']['#subrole_user_roles'] in a form_alter. The subroles of that role are then offered.

Hooks

Modules can add permissions that a subrole can never grant with hook_subroles_non_grantable_permissions_alter(), see subroles.api.php.

Tests

vendor/bin/phpunit -c web/core path/to/subroles

Troubleshooting

A user does not get the permissions of a subrole: check that the user also has the parent role. Without it, the subrole has no effect.
The "Subroles" field is not in the user form: enable it in each form display (and form mode) in use, and check the view and assign permissions.
A permission is disabled in the subrole form: it is restricted and you need to have it yourself, or manage restricted subrole permissions.

Changelog

See CHANGELOG.md.

javierms / subroles

Package info

Security

Statistics