Creating a New ACL Entry

In MODX Revolution, Access Control List (ACL) entries are used to protect resources (i.e., hide them from certain users) in both the front and back end and to determine what users can do and see in the MODX Manager. ACL entries are also used to protect elements (snippets, plugins, templates, template variables, and chunks) in the MODX Manager.

Because all security restrictions created with ACL entries apply to user groups, the way to get to the ACL panel is through the User Groups tab in Security | Access Controls.

Here are the general steps to creating any ACL entry:

  1. Go to Security | Access Controls
  2. Click on the "User Groups" tab if it's not the current tab
  3. Right-click on the User Group you want an ACL entry for
  4. Select "Update User Group"
  5. Click on one of the three right-most tabs, depending on which kind of ACL entry you need
  6. Click on the "Add . . ." button
  7. Enter the appropriate information (see below)
  8. Click on the "Save" button in the dialog
  9. click on the "Save" button at the upper right

There are three kinds of ACL entries — listed on the three right-most tabs of the Update User Group panel. They refer to Contexts, Resources, and Elements.

Unlike MODX Evolution, there are no Web and Manager users in Revolution — just users. For simplicity, however, we'll still use those terms here to describe users who are intended to operate in either the front or back end of the site. Bear in mind, however, that they are all just users as far as MODX is concerned. Their access is determined by the ACL entries for the User Groups they belong to and some (or all) users can be both web and Manager users.

Context Access ACL Entries

Context Access ACL entries determine which User Groups can access which Contexts (e.g., web and mgr) and what actions they can perform in those Contexts. The "mgr" Context is the MODX Manager. Manager users need a Context Access ACL entry granting them rights to the "mgr" Context. Without it, they can't log in to the Manager. The specific Permissions in the Policy associated with that ACL entry determine what the users can do and see in the Manager.

To create a Context Access ACL entry:

  1. Follow the steps at the top of this page to reach the Update User Group panel
  2. Click on the Context Access tab
  3. Click on the "Add Context" Button at the upper left
  4. Select the appropriate Context, Minimum Role, and Policy using the drop-down menus
  5. Click on the "Save" button in the dialog
  6. Click on the "Save" button at the upper right

The Context is the Context where you want the ACL entry to apply

The Minimum role determines which users in the user group the ACL entry will apply to. Users with a Role in the group that has an Authority number equal to or lower than that of the Minimum Role will have the permissions granted by the ACL entry.

The Access Policy contains the Permissions that may be granted to the users. If a permission is checked in the Policy, all users with the necessary Minimum Role will have that Permission.

All Context Access ACL entries should have a Policy that is a subset of the standard Administrator Policy. Appropriate Policies include the Administrator Policy, the Content Editor Policy, the Load Only Policy and the Load, List, and View Policy. The Object Policy is seldom used.

The "web" Context is the front end of the site, with one exception: Manager users must have a "web" Context Access ACL entry in addition to their "mgr" Context Access ACL entry in order to see resources in the "web"Context in the Tree in the Manager. Almost all the Context Access ACL entries you create will be for the "mgr" Context. If you want to hide resources in the front end for users who are not logged in, that should be done with Resource Group Access ACL entries. Except for the one "web" Context Access ACL entry for Manager Users mentioned above, there are only two common cases where you'd want to use a "web" Context Access ACL entry: 1) multi-language sites with each language in a different front-end Context; 2) One MODX core serving more than one site, with each site in a different front-end Context.

We've discussed the "mgr" and "web" Contexts here, but any other Contexts you create will be the equivalent of the "web" Context. Everything we've said about the "web" Context will apply to them as well.

Resource Group Access ACL Entries

Resource Group Access ACL entries are used to hide resources from users in the Manager or the front end of the site. In the Manager, they can also be used to control what users can do with the resources in the Resource Group (e.g., edit, duplicate, save, publish, etc).

If you create a Resource Group Access ACL entry with a Context of "web" that links that Resource Group to a specific User Group, only logged-in members of that User Group can see those resources in the front end of the site. If you do the same with a Context of "mgr" only Manager users who are members of that User Group can see the Resources int he Resource Group in the Resource tree in the Manager. That's why it's a good idea to add the admin Super User to every User Group to prevent hiding resources from yourself.

To create a Resource Group Access ACL entry:

  1. Follow the steps at the top of this page to reach the Update User Group panel
  2. Click on the Resource Group Access tab
  3. Click on the "Add Resource Group" Button at the upper left
  4. Select the appropriate Resource Group, Context, Minimum Role, and Policy using the drop-down menus
  5. Click on the "Save" button in the dialog
  6. Click on the "Save" button at the upper right

The Resource Group is the group of resources you want to protect by connecting them with the User Group you're updating.

The Context is the Context where you want the ACL entry to apply

The Minimum role determines which users in the user group the ACL entry will apply to. Users with a Role in the group that has an Authority number equal to or lower than that of the Minimum Role will have the permissions granted by the ACL entry.

The Access Policy contains the Permissions that may be granted to the users. If a permission is checked in the Policy, all users with the necessary Minimum Role will have that Permission.

Element Category Access ACL Entries

Elements (snippets, chunks, plugins, templates, and template variables) can't be placed in Resource Groups, but they can be placed in Categories. To protect them, you place them in a Category (creating the Category first, if necessary) and create a Category Access ACL entry. This is essentially the same process you use for Resource Group Access ACL entries only it works with elements rather than resources.

Note that if you want to hide all elements from certain users, the simplest method is to uncheck the element_tree permission in the appropriate Policy attached to a "mgr" Context Access ACL entry. The Element tree will not appear for those users and they will see no elements.

To create an Element Category Access ACL entry:

  1. Follow the steps at the top of this page to reach the Update User Group panel
  2. Click on the Element Category Access tab
  3. Click on the "Add Category" Button at the upper left
  4. Select the appropriate Category, Context, Minimum Role, and Policy using the drop-down menus
  5. Click on the "Save" button in the dialog
  6. Click on the "Save" button at the upper right

The Resource Group is the group of resources you want to protect by connecting them with the User Group you're updating.

The Context is the Context where you want the ACL entry to apply

The Minimum role determines which users in the user group the ACL entry will apply to. Users with a Role in the group that has an Authority number equal to or lower than that of the Minimum Role will have the permissions granted by the ACL entry.

The Access Policy contains the Permissions that may be granted to the users. If a permission is checked in the Policy, all users with the necessary Minimum Role will have that Permission.

Policies and Policy Templates

We'll finish with a word about Policies and Policy Templates. A policy is just a list of specific Permissions that can be granted or denied to users. Each permission allows the user to see something or to perform a specific action. Each Policy is based on a Policy Template. Policy Templates simply determine which Permissions appear in that Policy. You can check our uncheck any Permission to grant or deny that ability to any user. When you create Policies for User Groups, you should always duplicate one of the standard Policies, but you could use the standard Administrator, Resource, and Element Policy Templates for all of them and simply uncheck the Permissions you don't want the users to have. The only reason for using an alternate Policy Template is to keep you from having to wade through a long list of Permissions that you'll never use. Typically, the only time you need to create a new Policy Template is if you want to add Custom Permissions to the template. The most common reason for doing that is to use the Custom Permissions to hide Top Menu items from some users.

You should never modify the standard Policies or Policy Templates provided in the basic MODX install. If, for example, you modify the standard Administrator Policy to uncheck some permissions, you will be taking those permissions away from the Admin super user. If you remove Permissions from the standard Administrator Policy Template, you will also be taking away those Permissions from the Admin super user. That goes for the other standard Policies and Policy Templates as well. Always duplicate Policies or Policy Templates and alter the duplicates.

Security Resources at Bob's Guides

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting BobsGuides.com

  —  Bob Ray