Fine‑Tuning MODX Access: Custom Permissions, Roles, and Resource‑Scoped Security

Why Custom Permissions Matter in MODX

When a website grows beyond a single editor, you’ll quickly hit a wall: every new user gets the same blanket access that the Administrator has. That’s a security risk and a maintenance nightmare. MODX Revolution solves this by letting you create custom permissions and bind them to roles. From there, you can even limit a user’s rights to specific pages using the Resource Permissions tab. This article walks through the exact steps to set up a custom permission, attach it to a role, apply it to a resource, and verify the change works.

Problem Statement

Our team needed a way to let a junior content editor add and edit only the “News” section of the site, without touching any other pages. The default roles (Administrator, Manager, Publisher) either gave too much power or were too restrictive. We required a granular, repeatable solution that could be applied to multiple editors.

Thesis

By defining a custom permission, assigning it to a role, and scoping that role to the desired resources, you can enforce the principle of least privilege while keeping the workflow efficient.

Step 1 – Create a Custom Permission

1. Log into the MODX Manager.
   
   • Navigate to Security > Permissions.
2. Click New Permission.
   • Set Name to edit_news.
   • Set Description to “Can edit resources in the News folder”.
   • Leave Is System unchecked – this is a user‑defined permission.
3. Click Save.

After saving, the permission appears in the list. Note that the Manager UI caches permission data, so you may need to clear the cache before the new permission is available to users.

Step 2 – Attach the Permission to a Role

1. Go to Security > Roles.
2. Choose an existing role (e.g., Editor) or create a new one.
   • If creating new, click New Role, name it News Editor, and save.
3. Open the role and click Permissions.
4. Find edit_news in the list, check the box, and click Save.

Now any user assigned to this role will have the edit_news permission in addition to the role’s default permissions.

Step 3 – Scope the Permission to the News Resource

Suppose the News section lives under the resource with ID 42 (the “News” page). You’ll grant the role permission only on that page and its children.

1. Open the News resource in the Manager.
2. Click the Resource Permissions tab.
3. In the Allow column, select the News Editor role.
   • Leave the Deny column empty.
4. Click Save.

From now on, only users with the News Editor role can edit this resource or any child resources within the News folder.

Step 4 – Verify the Configuration

Verification is two‑step: confirm the permission is enforced, and confirm the cache cleared.

1. Create a test user (e.g., testuser) and assign the News Editor role.
2. Log in as testuser.
   • Navigate to the News resource; you should see the Update Resource button.
   • Navigate to another page (e.g., Home); the update button should be hidden or disabled.
3. Check the MODX logs (/assets/logs/manager.log) for entries like:

   [2026-10-12 22:15:00] User 5 attempted to update resource 42 without permission.
   

4. Clear the cache by deleting the /assets/cache/ directory or using the CLI:

   php modx.phar cache:clear
   

5. After cache removal, re‑log in and repeat the page navigation to ensure the permissions are freshly evaluated.

Trade‑Offs and Limitations

• Permissions are static strings. Renaming a permission (e.g., edit_news to edit_news_section) does not automatically update roles. You must manually re‑assign or update the role.
• Because the Manager UI caches permission data, changes may not appear until the cache is cleared or the user logs out and back in. In production, schedule cache clears during low‑traffic windows.
• Granting a permission to a broad role like Administrator defeats the purpose of fine‑grained control. Always audit role assignments against the least‑privilege principle.

Actionable Takeaway

To keep your MODX site secure and manageable: create custom permissions for every distinct action, bundle them into roles that match your team structure, and scope those roles to the relevant resources. Always test with a dummy user and clear the cache to ensure the changes propagate.

With this pattern, you can add new editors, restrict them to specific sections, and roll back changes by simply adjusting role assignments or permission scopes—no code changes required.