Drupal User Roles and Permissions — Granular Access Control Guide

In this tutorial, you'll learn how Drupal user roles and permissions work, how to create custom roles, configure granular permissions per content type and module, and implement secure access control for your site.

What You'll Learn

• What Drupal permissions are and how every action maps to a permission string
• The default Anonymous and Authenticated user roles
• How to create custom roles via People > Roles
• Configuring permissions on the People > Permissions page per module and entity
• Content type permissions: create, edit, delete own, delete any
• Node, taxonomy term, and user permissions
• System permissions like administer modules and site configuration
• Permission inheritance when users have multiple roles
• Role weight and administration settings
• Checking access in code with \Drupal::currentUser()->hasPermission()
• User cancel action configuration
• Permissions for custom modules
• Best practices: Least Privilege principle

Why It Matters

Drupal's permission system is one of the most granular in any CMS. Every action — from "creating an article" to "administering modules" — is controlled by a permission string. This means you can give each user exactly the access they need and nothing more. For enterprise sites with editors, reviewers, publishers, and administrators, this granularity prevents accidental changes, protects sensitive content, and maintains editorial workflows. Getting permissions wrong leads to security holes or locked-out users. Getting them right gives you a production-ready access control system.

Real-World Use

A government agency publishing hundreds of regulatory documents needs different access levels: content authors write drafts, senior editors review and approve, publishers push live, and administrators manage the system. Without granular permissions, authors might accidentally publish unapproved content or editors might change site configuration. Drupal's role and permission system enforces this workflow. The same approach applies to universities, newsrooms, and e-commerce sites where different teams manage different content types.

Learning Path

flowchart LR
  A[Admin Dashboard] --> B[Content Types]
  B --> C[Fields]
  C --> D[User System]
  D --> E[Roles and Permissions]
  E --> F[User Management]
  F --> G[Security Hardening]
  G --> H[Custom Modules]
  H --> I[Hooks and APIs]

Understanding Drupal Permissions

In Drupal, a permission is a string that controls access to a specific action. Every action your site performs — viewing content, creating articles, administering modules, deleting users — has a corresponding permission string.

Permission strings follow this pattern: module_name action. For example:

• node article create: create an article content type
• administer nodes: administer all content
• access content: view published content
• administer users: manage user accounts

These strings are stored in the database and checked by Drupal's access system whenever a user tries to perform an action.

How Permissions Work with Roles

A role is a named set of permissions. When you assign a role to a user, the user inherits all permissions from that role. A user can have multiple roles, in which case they inherit the combined permissions of all their roles.

Think of roles like keys. Each role is a keyring with specific keys (permissions). Give a user two keyrings, and they can unlock everything on both rings.

Default Roles

Drupal comes with two default roles that you cannot delete:

Anonymous User

The Anonymous role applies to anyone who is not logged in. By default, anonymous users can view published content. You control exactly what anonymous visitors can see and do. For most sites, anonymous users can only view content and submit contact forms.

Authenticated User

The Authenticated role applies to every logged-in user. This role sits between anonymous access and full admin access. Authenticated users typically can create and edit their own content, manage their profiles, and view restricted content.

Both default roles serve as baseline permissions. You layer custom roles on top.

Creating Custom Roles

To create a custom role:

1. Go to People > Roles (/admin/people/roles)
2. Click Add role
3. Enter a Role name (e.g., "Content Editor", "Publisher", "Moderator")
4. Click Save

# Example: roles in your system
- Content Author: can create and edit own articles
- Senior Editor: can edit any content, manage revisions
- Publisher: can publish and unpublish content
- Site Administrator: has all permissions except module administration

Each role gets a machine name and a weight. The weight determines ordering on user profiles but does not affect permission inheritance.

Configuring Permissions

Navigate to People > Permissions (/admin/people/permissions). You'll see a large table:

• Rows: each permission string grouped by module
• Columns: each role on your site
• Checkboxes: grant a permission to a role

Permission Categories

Permissions are organized by the module that provides them. Here are the key categories:

Node Permissions

For each content type, Drupal creates four permissions:

• [type]: create new content — allows creating new nodes of this type
• [type]: edit own content — allows editing content the user created
• [type]: edit any content — allows editing any content of this type
• [type]: delete own content — allows deleting own content
• [type]: delete any content — allows deleting any content

Example for Article content type:

// These are the permission strings generated for Article
// node.article.create:create
// node.article.edit:own
// node.article.edit:any
// node.article.delete:own
// node.article.delete:any

Taxonomy Term Permissions

For each vocabulary, you can control who can edit and delete terms:

• edit terms in [vocabulary] — allows editing terms in this vocabulary
• delete terms in [vocabulary] — allows deleting terms in this vocabulary

User Permissions

• access user profiles — view other users' profile pages
• cancel account — allows users to cancel their own accounts
• change own username — allows users to change their displayed username

System Permissions

• administer modules — install, update, and uninstall modules
• administer site configuration — change site settings
• access administration pages — access the admin interface
• view the administration theme — see the admin theme

Permission Inheritance

When a user has multiple roles, their effective permissions are the union of all role permissions. There is no deny mechanism — if any role grants a permission, the user has it.

// Example: user with two roles
// Role A: Content Author (can create articles)
// Role B: Administrator (can administer modules)
// Result: user can both create articles AND administer modules

This is important: you cannot create a "blocking" role that revokes permissions from another role. If you need to remove a permission, you must remove it from all roles the user has.

Role Weight

Each role has a weight that controls its position in the user interface. Lower-weight roles appear first. The weight does not affect permission resolution because permissions are purely additive.

Checking Access in Code

When building custom modules, you need to check whether the current user has a specific permission:

<?php
// Check if current user has a permission
$user = \Drupal::currentUser();
if ($user->hasPermission('administer nodes')) {
  // User can administer nodes
}

// Check for a custom permission from your module
if ($user->hasPermission('my_module special access')) {
  // User has special access
}

// Get the user's roles
$roles = $user->getRoles();
// Returns: ['authenticated', 'content_editor']

Route-Level Access

You can also check permissions in routing YAML:

# my_module.routing.yml
my_module.my_page:
  path: '/my-page'
  defaults:
    _controller: '\Drupal\my_module\Controller\MyController::page'
    _title: 'My Page'
  requirements:
    _permission: 'my_module special access'

Dynamic Access with Access Checks

For complex logic, create a custom access checker:

<?php
namespace Drupal\my_module\Access;

use Drupal\Core\Access\AccessResult;
use Drupal\Core\Routing\Access\AccessInterface;
use Drupal\Core\Session\AccountInterface;

class MyAccessCheck implements AccessInterface {
  public function access(AccountInterface $account) {
    // Custom logic: check node author, time, etc.
    if ($account->hasPermission('my_module special access')) {
      return AccessResult::allowed();
    }
    return AccessResult::forbidden();
  }
}

User Cancel Action

When a user cancels their account, you can configure what happens:

1. Disable the account — the user cannot log in but content remains
2. Disable and unpublish content — user is blocked and all their content is unpublished
3. Delete the account — user is removed entirely, content can be reassigned

Configure this at Configuration > People > Account settings (/admin/config/people/accounts).

Permissions for Custom Modules

When creating a custom module, define permissions in a .permissions.yml file:

# my_module.permissions.yml
'my_module special access':
  title: 'Access special features'
  description: 'Allows users to access the special features of My Module'
  restrict access: true

'my_module administer':
  title: 'Administer My Module'
  description: 'Allows users to configure My Module settings'
  restrict access: true

Then use these permissions in routing and access checks.

Best Practices

Least Privilege Principle

Give each role the minimum permissions needed. A content author does not need administer modules. A publisher does not need access user profiles.

Role Design Patterns

• Content Author: create/edit own content for specific types
• Senior Editor: edit any content, manage revisions, but not delete
• Publisher: publish/unpublish content, manage moderation states
• Admin: full access excluding security-related permissions

Audit Regularly

Review permissions periodically. Remove unused permissions from roles. Check for roles that have accumulated unnecessary access over time.

Use Test Users

Create test user accounts for each role and verify that they can only do what you expect. This catches misconfigured permissions before they reach production.

Common Mistakes

1. Giving too many permissions to Authenticated role: Every logged-in user inherits from Authenticated. Adding powerful permissions here gives them to everyone. Keep Authenticated minimal and use custom roles instead.

2. Not realizing permissions are additive: You cannot block a permission by removing a role. If a user has two roles, they get all permissions from both. Design roles carefully to avoid unintended combinations.

3. Forgetting to configure cancel behavior: By default, Drupal allows account cancellation. If you do not configure the cancel action, users might delete their accounts and leave orphaned content.

4. Using administer nodes instead of granular permissions: This permission gives full control over all content. Use per-content-type permissions instead to allow editing articles without touching pages.

5. Not testing permissions before launch: Assigning permissions in the UI is fast. But you must test each role with a real user account to verify that editors cannot publish and publishers cannot administer modules.

Practice Questions

1. A user has both "Content Author" (create/edit own articles) and "Publisher" (publish any content). Can they publish an article they did not create? Why?
2. How would you set up a permission system where interns can create articles but cannot edit articles created by full-time staff?
3. What happens to a user's content when you cancel their account using the "Delete the account" method?
4. Challenge: Design a role hierarchy for a news website with roles for reporters, editors, section editors, publishers, and administrators. List the minimum permissions each role needs. Consider that reporters should only edit their own drafts, editors should edit any content in their section, and publishers should control go-live.

FAQ

Mini Project

Goal: Create a content approval workflow using roles and permissions.

1. Create three roles: Author, Reviewer, Publisher
2. Create a content type called "Report" with fields: title, body, status (draft/review/published)
3. Configure permissions:
   • Author: create Reports, edit own Reports
   • Reviewer: edit any Reports
   • Publisher: edit any Reports, delete any Reports, administer nodes
4. Create one test user for each role
5. Log in as each user and verify they can only perform their assigned actions
6. Write a PHP script using \Drupal::currentUser()->hasPermission() to enforce the workflow in a custom module
7. Document any permission gaps you found and how you fixed them

What's Next

Now that you understand roles and permissions, proceed to user management to learn about registration, profiles, and user administration. Then explore security hardening to protect your Drupal site from common vulnerabilities.