MODX ACLs - Confusion to Clarity to Creative Freedom

Oct 10, 2012

The Problem

You've used MODX Revolution for years, but there's always been this nagging feeling that you're "missing something" about Access Control Lists, or ACLs. It's a common perception that this is the area of Revo with the steepest learning curve.


This post is NOT a tutorial. I'm going to talk about the WHY of MODX Revolution ACLs. There are some great resources around for learning the HOW:

Official Documentation:

Ben Marte's Post:

Bob's Massive Guide to Revo Permissions:

Bob's Revo Permissions Cheat Sheet:

The Concepts

There's a lot more to this topic than what we're talking about here, but we're aiming for a quick, easy-to-grasp conceptual understanding of what's going on behind the scenes. Hopefully this will help you implement any permissions/security structure you may require.

Anyone logging into a MODX site does so as a User. To be able to login, a User must belong to a User Group and be assigned a Role. A User can only play one Role in any given User Group. Let's use an analogy: a User is a person, a User Group is a company, and a Role is a job. Our first MODX permissions Concept is:

"Any person must have a job at a company. They may not have more than one job at a company, but they can have different jobs at different companies."

User Groups, or companies, are just organizations of Users. Many sites only require the two default User Groups: Administrators and Anonymous. There's specific use cases where multiple User Groups become necessary, and I'll go into those below; but first let's talk about Roles.

A Role can be anything you like, and can have any combination of Permissions you want. By default there are two Roles: Super User and Member but these are arbitrary. The way that Roles get their permissions to do stuff on the site is that you associate the Role with an Access Policy, or a pre-configured set of permissions. Access Policies are like job descriptions. So Concept #2:

"Based on a person's job, they have a job description, and within that company, that job description is all they're allowed to do."

 The Simplest Use Case

On a very basic level, you know almost everything you need to know. Let's say you want to give your client access to the Manager to upload content, but you don't want them to bork the site. At the most basic level, all you need is to create a Role ("job") with the desired Access Policy ("job description"), then put that User ("person") into the default Administrator User Group ("company") with that Role.

"Give your client a job in the Administrators company, and give that job a job description."

Giving the job a job description requires one more piece of the puzzle - Context Access. To add more Roles to a User Group, you need to associate those Roles with Access Policies using the Context Access tab (when editing a User Group). Put a simpler way:

"To expand the company with more jobs, you need to provide those jobs with job descriptions by writing company guidelines."

Company guidelines need to have the following information:

  1. What Role, or job, are you creating at the company?
  2. What Access Policy will the Role use, or what will the job description of the job be?
  3. In which Context will the above apply. Contexts are like company divisions, so what company division will the new job belong to?

A job can be in more than one company division. In fact it probably needs to be. The "mgr" Context is the company division that works in the MODX Manager. But the "web" context is the front-end, website division. Any User in MODX will need access to the "web" context if they want to view the website itself. This is an important adendum to one of the Concepts above:

"A person can only have one job in a company, but that job can have different job descriptions depending on which division they're working in."

This has many ramifications and starts to lead us down the path towards the more powerful capabilities of MODX Revolution permisisons. A Context in MODX can be used for anything you like, but the purposes for which it was designed include multi-language sites or mulitple locations for the same organization. So going with our divisions analogy, let's say you have a person with a job, and their job description is "Site Administrator with Full Permissions" - well that can be limited to the North American location (or Context). In the European location, that person's job description is "Content Editor Only". 

It might be useful to note here that when assigning Context Access, or writing company guidelines, the term "Minimum Role" pops up. That just means that you set the job with the least authority, the lowest on the totem pole, with a certain job description, and then any higher authority job like "Super User" will inherit that job description. WIth great power, comes great responsibility, right? Set a Minimum Role of Super User, and only the boss, or highest authority User, will have those permissions. Set a Minimum Role of Member and all other Roles will also share those permissions.

You see how flexible this is? We haven't even started with multiple User Groups yet. All these options can be implemented within the default Administrator User Group.

Why Multiple User Groups?

If you can do all of the above with just the default User Group(s), why use multiples at all? The main reason, among a plethora of others, is Resource Groups. Resource Groups can be likened to industries. When a Resource Group, or industry, is defined, nothing has changed yet. But when a User Group is given access to a Resource Group, that User Group gets exclusive access to it. This is Concept #3:

"A company can be granted a monopoly over a certain industry."

No other company can work in that industry unless you specifically grant that "other" company access as well, in which case you have a polygopoly. 

As you probably already know, Resource Groups can have any number of Resources, or web pages, inside of them. This limits access to those pages, but you have to define who gets access, and under what conditions. When you assign a Resource Group to a User Group, you need to define the Role and Access Policy associated with it. Put another way:

"For every industry a company does business in, the jobs, job description, and division of the people working in the industry must be defined."

So an example setup, including everything we've talked about so far, might be:

  1. Super Users, or bosses, can do everything, in any division of the company, in any industry the company does business in.
  2. Content Editors, or managers, can do some stuff, in any division of the company, in any industry the company does business in.
  3. Registered Users, or interns, can't do anything except view stuff in the "web" division (no Manager access), in any industry the company does business in (they can visit private pages).
  4. Non-Registered Users, or those outside the company (in the Anonymous User Group) can't do anything except view stuff in the web division, and they can't view stuff in the chemical industry (restricted from private pages).

There are an infinite number of possible configurations here, and we're only touching on key concepts. If you get down into the nuts and bolts, you will either go insane or reach a previously unfathomable level of enlightenment. MODX is all about Creative Freedom, and this system gives you ultimate flexibility on User Management. Sure, it's harder to learn than Evolution permissions, but isn't your Freedom worth a little extra effort?