MODX Roles and Permissions System

Comprehensive guide to MODX's powerful and flexible role-based access control (RBAC) system, including user groups, roles, access policies, and context permissions.

Understanding MODX's Permission Architecture

Four-Layer Permission Model

MODX uses a sophisticated permission system with four interconnected components:

1. Users (Individual accounts)
   ↓
2. User Groups (Teams/Categories)
   ↓
3. Roles (Authority levels within groups)
   ↓
4. Access Policies (Specific permissions)
   ↓
Applied to: Contexts, Resource Groups, Elements

How they work together:

• User belongs to one or more User Groups
• Each membership has a Role (authority level)
• User Group + Role gets Access Policies
• Access Policies grant specific Permissions
• Applied to Contexts (mgr, web, custom)

Permission Evaluation Flow

User logs in
  ↓
MODX checks: What User Groups?
  ↓
For each User Group: What Role?
  ↓
What Access Policies apply to this User Group + Role?
  ↓
What Contexts/Resources can they access?
  ↓
What specific permissions do they have?
  ↓
Grant or deny access

User Groups

What Are User Groups?

Definition: Collections of users with similar access needs.

Purpose:

• Organize users by team, department, or function
• Apply permissions to groups instead of individuals
• Simplify permission management
• Create organizational hierarchy

Examples:

• Administrators
• Content Editors
• Marketing Team
• Support Staff
• Developers
• Clients

Default User Groups

MODX includes one default user group:

Administrator:

• Pre-configured for full access
• Super User role with AdministratorPolicy
• Access to all contexts
• Can do everything

Creating User Groups

Via Manager Interface

Security → Access Controls → User Groups → New User Group

Settings:

• Name: Group identifier (e.g., "Content Editors")
• Description: Purpose of group (optional)
• Parent: Hierarchical parent group (optional)

Example groups:

└── Company
    ├── Administrators
    ├── Content Team
    │   ├── Content Editors
    │   └── Content Authors
    ├── Marketing
    └── Developers

Programmatically

<?php
// Create user group
$userGroup = $modx->newObject('modUserGroup');
$userGroup->set('name', 'Content Editors');
$userGroup->set('description', 'Users who edit website content');
$userGroup->save();

echo "User Group created: ID " . $userGroup->get('id');

Roles

Understanding Roles

Definition: Authority level within a user group.

Key concept: Lower number = higher authority

Authority values:

• 0 = Highest authority (Super User)
• 9999 = Standard authority (Member)
• Custom values in between

Purpose:

• Define hierarchy within groups
• Determine which policies apply
• Control access levels
• Create approval workflows

Default Roles

Super User (Authority: 0):

• Highest authority level
• Bypasses most restrictions
• Administrative privileges
• Typically for user ID 1 and trusted admins

Member (Authority: 9999):

• Standard member authority
• Default role for most users
• Lower privileges than Super User

Creating Custom Roles

Via Manager

Security → Access Controls → Roles → New Role

Settings:

• Name: Role identifier (e.g., "Editor in Chief")
• Description: Role purpose
• Authority: Numeric authority level

Example roles:

Role Name          | Authority | Use Case
-------------------|-----------|----------------------------------
Super User         | 0         | Full administrative control
Administrator      | 100       | Site administration
Manager            | 500       | Department management
Senior Editor      | 800       | Editorial oversight
Editor             | 9998      | Content editing
Contributor        | 9999      | Basic content contribution

Authority-Based Permissions

How authority works:

Access Policy: "Minimum Role: 500"

Users with roles:
- Super User (0): ✓ Access granted (0 ≤ 500)
- Administrator (100): ✓ Access granted (100 ≤ 500)
- Manager (500): ✓ Access granted (500 ≤ 500)
- Senior Editor (800): ✗ Access denied (800 > 500)
- Editor (9998): ✗ Access denied (9998 > 500)

Lower authority value = more access

Access Policies

What Are Access Policies?

Definition: Collections of permissions that define what users can do.

Structure:

• Named collection of permissions
• Defines specific capabilities
• Can be applied to contexts, resource groups, elements
• Reusable across user groups

Default Access Policies

Administrator Policy

Full system access:

• All manager permissions
• Element editing
• System settings
• User management
• Package management

Use for: System administrators

Content Editor Policy

Content management permissions:

• Create/edit/publish resources
• Manage resource tree
• Upload files
• Basic element access
• Limited settings access

Use for: Content editors and managers

Load Only Policy

Read-only access:

• View resources
• Access manager
• No editing permissions
• No publishing

Use for: Reviewers, clients (view-only)

Resource Policy

Frontend resource permissions:

• Load resources
• View published content
• Frontend-only access

Use for: Frontend user groups

Creating Custom Access Policies

Via Manager

Security → Access Controls → Access Policies → New Access Policy

Step 1: Create Policy

• Name: Policy identifier (e.g., "Blog Editor Policy")
• Description: Policy purpose
• Policy Template: Choose template (Administrator, Resource, etc.)
• Lexicon: Language topic

Step 2: Assign Permissions

After creating, edit policy to select permissions:

Edit Policy → Policy Permissions tab

Select specific permissions:

• ☑ load - View manager
• ☑ view - View resources
• ☑ save - Save resources
• ☑ new_document - Create resources
• ☑ publish_document - Publish resources
• ☑ delete_document - Delete resources
• ☐ remove - Permanently delete (uncheck for safety)
• ☑ file_upload - Upload files
• ☐ settings - Change settings (restricted)

Example: Blog Editor Policy

Purpose: Manage blog posts only

Permissions:

Content:
☑ load, view, list
☑ new_document, save, delete_document
☑ publish_document, unpublish_document
☑ view_document, edit_document

Files:
☑ file_upload, file_view
☐ file_manager (no full file manager access)

Elements:
☑ view_template (read-only templates)
☐ save_template (cannot edit templates)

Settings:
☐ settings (no settings access)

Users:
☐ All user permissions denied

Context Access

Understanding Contexts

Definition: Isolated environments within MODX.

Default contexts:

• mgr - Manager backend (admin area)
• web - Frontend website

Custom contexts: Can create for:

• Multiple websites
• Staging environments
• Different language sites
• Separate admin areas

Assigning Context Access

Via User Interface

Security → Manage Users → Edit User → Access Permissions

Add Context Access:

1. Click "Add Context Access"
2. Select Context (mgr, web, etc.)
3. Select User Group (user must be member)
4. Select Minimum Role required
5. Select Access Policy
6. Save

Example:

User: John Doe
└── Context Access
    ├── mgr (Manager)
    │   ├── User Group: Content Editors
    │   ├── Minimum Role: Member (9999)
    │   └── Policy: Content Editor Policy
    └── web (Frontend)
        ├── User Group: Content Editors
        ├── Minimum Role: Member (9999)
        └── Policy: Load Only Policy

Programmatically

<?php
// Grant context access to user group
$userGroup = $modx->getObject('modUserGroup', array('name' => 'Content Editors'));
$policy = $modx->getObject('modAccessPolicy', array('name' => 'ContentEditorPolicy'));

if ($userGroup && $policy) {
    $acl = $modx->newObject('modAccessContext');
    $acl->set('target', 'mgr'); // Context
    $acl->set('principal', $userGroup->get('id')); // User Group
    $acl->set('authority', 9999); // Minimum Role (Member)
    $acl->set('policy', $policy->get('id')); // Access Policy
    $acl->save();
}

Resource Group Access

What Are Resource Groups?

Definition: Collections of resources for group-based permissions.

Purpose:

• Restrict access to specific content sections
• Create client-specific areas
• Limit editing to certain folders
• Departmental content isolation

Creating Resource Groups

Security → Access Controls → Resource Groups → New Resource Group

Settings:

• Name: Group identifier (e.g., "Blog Posts")
• Description: Purpose

Assigning Resources to Groups

Edit resource:

Edit Resource → Settings tab → Resource Groups

Add to group:

• Select resource group(s)
• Resources can belong to multiple groups
• Save resource

Granting Resource Group Access

Security → Access Controls → User Groups → Edit Group
→ Resource Group Access tab

Add access:

1. Select Resource Group
2. Select Context
3. Select Minimum Role
4. Select Access Policy
5. Save

Example: Blog-only access

User Group: Blog Editors
└── Resource Group Access
    └── Resource Group: Blog Posts
        ├── Context: web
        ├── Minimum Role: Member (9999)
        └── Policy: Resource Policy

Element Category Access

Restricting Element Access

Elements: Templates, Chunks, Snippets, Plugins, Template Variables

Purpose:

• Limit template editing
• Protect custom snippets
• Prevent accidental changes
• Developer-only elements

Assigning Element Category Access

Security → Access Controls → User Groups → Edit Group
→ Element Category Access tab

Settings:

1. Select Element Category
2. Select Context
3. Select Minimum Role
4. Select Access Policy
5. Save

Example: Allow viewing but not editing templates

User Group: Content Editors
└── Element Category Access
    └── Category: Templates
        ├── Context: mgr
        ├── Minimum Role: Member (9999)
        └── Policy: Load Only Policy (view but not edit)

Common Permission Scenarios

Scenario 1: Content Editor

Requirements:

• Edit website content
• Publish articles
• Upload images
• Cannot change settings or users

Setup:

User Group: Content Editors

Context Access (mgr):

• Policy: ContentEditorPolicy
• Minimum Role: Member

Permissions include:

• Create, edit, delete, publish resources
• Upload files
• View templates (read-only)
• No settings access
• No user management

Scenario 2: Blog-Only Editor

Requirements:

• Edit blog posts only
• Cannot access other site sections
• Can upload blog images

Setup:

Resource Group: Blog Posts (contains blog resources)

User Group: Blog Editors

Resource Group Access:

• Resource Group: Blog Posts
• Policy: Resource Policy
• Can only edit resources in blog group

Restricted from:

• Other website pages
• Settings
• Users

Scenario 3: Client Access (View-Only)

Requirements:

• View site progress
• Cannot edit anything
• See draft content

Setup:

User Group: Clients

Context Access (mgr):

• Policy: Load Only Policy
• Minimum Role: Member

Permissions:

• View resources (cannot edit)
• Access manager (read-only)
• No create/delete/publish
• No settings

Scenario 4: Department Managers

Requirements:

• Full control over department resources
• Manage department users
• Cannot access other departments

Setup:

User Group: Marketing Department

Resource Group: Marketing Content

Resource Group Access:

• Policy: AdministratorPolicy (for marketing resources only)
• Can manage users in Marketing group
• Cannot see other departments

Scenario 5: Developer Access

Requirements:

• Edit templates, snippets, plugins
• Package installation
• System settings
• No content editing

Setup:

User Group: Developers

Context Access (mgr):

• Policy: Custom "Developer Policy"

Custom policy permissions:

Elements:
☑ All element permissions

Settings:
☑ settings, view_sysinfo

Packages:
☑ packages

Content:
☐ new_document, save_document (no content editing)

Permission Inheritance

How Permissions Combine

User in multiple groups:

• Permissions are cumulative (not restrictive)
• User gets all permissions from all groups
• Cannot "revoke" permission from one group if granted by another

Example:

User: John
├── Group 1: Can view resources (Load Only Policy)
└── Group 2: Can edit resources (Content Editor Policy)

Result: John can EDIT (higher permission wins)

Best practice: Be careful with multiple group memberships.

Role Authority Combination

User with multiple roles:

• Lowest authority value wins (highest privilege)

Example:

User: Jane
├── Group 1: Role = Member (9999)
└── Group 2: Role = Super User (0)

Effective authority: 0 (Super User)
Jane has highest privileges

Security Best Practices

Principle of Least Privilege

Start minimal:

• ✓ Grant minimum permissions needed
• ✓ Use restrictive policies by default
• ✓ Add permissions only when required
• ✗ Don't grant AdministratorPolicy unless necessary

Separate Duties

Don't combine:

• Content editing + User management
• Development + Content editing (unless needed)
• Settings access + General editing

Create specific roles:

• Content Editor (content only)
• User Manager (users only)
• Developer (elements only)

Regular Audits

Monthly review:

• List all users and groups
• Verify permissions appropriate
• Check for unused accounts
• Review super user assignments
• Test permission restrictions

Dangerous Permissions

Use with extreme caution:

☐ save_role - Can create/edit roles
☐ delete_role - Can delete roles
☐ policy_edit - Can edit access policies
☐ usergroup_edit - Can modify user groups
☐ remove - Permanently delete (vs soft delete)
☐ settings - Change system settings
☐ file_manager - Full file system access

Troubleshooting Permissions

User Cannot Access Manager

Check:

1. User active and not blocked
2. User belongs to a user group
3. User group has context access to mgr
4. Policy includes load permission
5. Minimum role requirement met

User Cannot Edit Resources

Check:

1. User has save and save_document permissions
2. User has context access to appropriate context
3. Resource not protected by resource group
4. Role authority sufficient
5. Policy allows editing

User Sees Elements But Cannot Edit

Expected: View-only access

To grant edit access:

1. Change access policy to include element edit permissions
2. Or grant access to element category with editing policy

Permissions Not Taking Effect

Solutions:

1. Clear cache (Site → Clear Cache)
2. Have user log out and back in
3. Verify policy assignment
4. Check all user group memberships
5. Review context access settings

Next Steps

• Adding and Removing Users - User management
• MODX User Management - Overview
• MODX Security Documentation

Related Resources

• Access Control Lists (ACLs)
• Custom Access Policies
• User Groups

Quick Reference

Common Access Policies

Authority Levels Guide