Permissions by Term
Restricts access to nodes and taxonomy terms based on user accounts and/or user roles assigned to specific taxonomy terms.
permissions_by_term
Install
composer require 'drupal/permissions_by_term:^3.1'
Overview
The Permissions by Term module extends Drupal by providing functionality for restricting access to single nodes via taxonomy terms. Taxonomy term permissions can be coupled to specific user accounts and/or user roles. This allows site administrators to build access-restricted content areas on their websites using Drupal's core taxonomy functionality.
Since Permissions by Term uses Drupal's Node Access Records system, every other core system that relies on node access will respect these restrictions including: search results, menus, views, and direct node access.
The module provides a lightweight access control solution that restricts user access to specified Drupal nodes based on taxonomy terms - a core part of Drupal's functionality. This allows content access restriction while relying on very little contributed code.
Features
- Restrict access to nodes based on taxonomy term permissions assigned to users or roles
- Supports both user-specific and role-based term permissions
- Multilingual support - permissions are language-aware and stored per language
- Integrates with Drupal's Node Access Records system for consistent access control across search, menus, and views
- Settings form for configuring permission mode, vocabulary limitations, and display options
- Displays permission information on node edit forms showing allowed users and roles
- User form integration allowing administrators to assign term permissions directly to users
- Automatic term autocomplete filtering based on user permissions
- Drush command for rebuilding node access permissions
- Migration plugin support for importing term permissions
- Event system for reacting to access denied scenarios
- Cache system for optimized performance with access result caching
- Submodule (Permissions by Entity) extends functionality to non-node entities
Use Cases
Membership Site with Premium Content
Create a 'Member Access' vocabulary with terms like 'Free', 'Premium', 'VIP'. Assign the 'Premium' term permission to the 'Premium Member' role. Tag content with appropriate access terms. Free users see only 'Free' content, while premium members see both free and premium content.
School Website with Role-Based Access
Create an 'Audience' vocabulary with terms like 'Students', 'Teachers', 'Administrators'. Assign term permissions to corresponding user roles. Content tagged with 'Teachers' is only visible to users with the teacher role. This allows different content sections for different school stakeholders.
Company Intranet with Department-Based Access
Create a 'Department' vocabulary with terms for each department (HR, Engineering, Sales). Assign department terms to users in the user profile form. Tag internal documents and pages with department terms. Employees only see content relevant to their department.
Content Moderation Workflow
Enable 'Disable node access records' setting and use permissions to control who can edit unpublished content during editorial review. This allows editors to work on content without it appearing in public listings until published.
Multi-language Content Access
Since permissions are stored per language, create language-specific content restrictions. A term can grant access for the English version but not the German version of content, useful for regional content licensing.
Tips
- Always rebuild node access permissions after bulk changes to term permissions using the Drush command
- Use the 'Limit by taxonomy vocabularies' setting to restrict which vocabularies are used for permissions, improving performance
- Enable 'Hide terms permissions information in node form' on sites with many permissions for faster node form loading
- The 'Require all terms granted' setting is useful for creating content that requires multiple access levels
- Users with 'bypass node access' permission will always have access regardless of term permissions
- Consider using the Permissions by Entity submodule if you need to restrict access to media, paragraphs, or custom entity types
Technical Details
Admin Pages 1
/admin/permissions-by-term/settings
Configure global settings for the Permissions by Term module including permission modes, vocabulary restrictions, and display options.
Permissions 4
Hooks 8
hook_node_access_records
Implements node access records for term-based permissions. Creates grant records in the node_access table for nodes with restricted terms.
hook_node_grants
Provides the grants a user has for viewing nodes. Returns GIDs that the user is permitted to access based on their term permissions.
hook_node_access
Checks node access and dispatches denied event if access is restricted.
hook_form_taxonomy_term_form_alter
Adds the permissions fieldset to taxonomy term edit forms allowing users and roles to be assigned access.
hook_form_user_form_alter
Adds term permission assignment interface to user edit forms.
hook_options_list_alter
Filters taxonomy term options in select lists based on user permissions.
hook_taxonomy_term_delete
Cleans up term permissions when a taxonomy term is deleted.
hook_user_cancel
Deletes all term permissions for a user when their account is cancelled.
Drush Commands 1
drush permissions-by-term:rebuild
Rebuild node access records for all nodes managed by Permissions by Term. Useful after bulk changes to term permissions or when access records become out of sync.
Troubleshooting 5
Run node access rebuild at /admin/reports/status/rebuild or use 'drush permissions-by-term:rebuild'. Ensure the Dynamic Page Cache module is enabled.
Enable 'Disable node access records' in settings if you have many nodes. This improves performance on large non-cached listings but removes access control from Views.
Permission mode requires explicit grants. Ensure users have at least one term permission assigned, or disable permission mode for default open access.
Ensure the KernelEventListener is working properly. Check that users don't have 'bypass node access' permission which overrides all restrictions.
Ensure 'Disable node access records' is unchecked in settings. Verify the Dynamic Page Cache module is enabled.
Security Notes 6
- The module uses Drupal's Node Access Records system, which is the recommended way to implement content access control
- Users with the 'bypass node access' permission will bypass all term-based restrictions
- Anonymous users (uid 0) can be granted access to specific terms like authenticated users
- Term permissions are language-specific - a permission grant in English doesn't automatically apply to other language versions
- The 'show term permission form on term page' permission is marked as 'restrict access' - only grant to trusted roles
- Always test permission configurations thoroughly before deploying to production