Revolution Permissions

Permissions can be a confusing issue in MODx Revolution. There are more entities and more complex interactions between them than in MODx Evolution. The following information is for MODx Revolution and later. There is information on MODx Evolution permissions here.

Where It's Done

It helps to understand that there are really four different parts to the Revolution permissions system.

• Which resources users can see and what they can do with them is controlled by ACL entries.
• Visibility of the Elements tab and Files tab is controlled by specific permissions (element_tree, file_tree).
• Visibility and organization of the Top Menu is controlled in Manager | Actions.
• Which fields show up in specific forms (e.g. the Create/Edit Resource panel) for particular users is controlled in Security | Form Customization.

No More Web Users and Manager Users

In MODx Revolution, there is no longer any distinction between Manager Users and Web Users — there are just Users. Controlling access in the front and back ends is done with Contexts. Users in the back end are in the "mgr" Context, users in the front end are in the "web" Context (or other Context you create). By back end, we're referring to where you are when you log in via yoursite.com/manager and work in the MODx Manager. Users in the front end, on the other hand, are visiting the site via yoursite.com and may or may not be logged in through a form in the front end of the site.

In Revolution, a User at any given time is logged in or not logged in. A User in the MODx manager is logged in and in the "mgr" Context. A User in the front end is in the "web" Context (or other Context you create) and may be logged in or not. If not logged in, the User is an anonymous user with only the Permission to "load" Documents (i.e see them).

Basic Principles

In MODx Evolution, Documents are "protected" when a Document Group is assigned to a User Group. Once that's done, only Users who are given rights to the Documents can access them. Manager User/Manager Resource Group connections only apply in the back end (in the MODx Manager). WebGroup/WebUser connections only apply in the front end of the site.

In MODx Revolution, Documents and Contexts are protected in Access Control Lists (ACLs) (more on these later). Once a Document or Context is protected by a single ACL entry, it can only be accessed by Users who are given access to it in an ACL entry and that entry will determine what they can do.

Access permissions are listed in Access Policies. Those Policies are assigned in ACL entries with a specified Role and a specified Context. The Access Control Lists (ACLs) belong to a specific User Group and (unlike Evolution) different Users can be assigned different Roles in the group. This may sound like gibberish now, but it should become clear as we go along.

This system, while a little difficult to understand at first, gives you tremendous flexibility by allowing you to have Users in the same User Group who have access to the same Resources, but with different capabilities. With three Users in the same User Group, for example, one User might be able to see a Document in the tree, but not edit it. Another User might be able to see, edit, and save the Document but not publish, unpublish, or delete it. A third User might have full rights to the Document. Similarly, Users in a single User Group can have different capabilities in the MODx Manager.

I'll assume that you know, or can figure out, what a User, User Group, and Resource Group are ("Resource" is the official name for Documents, Weblinks, Symlinks, and Static Resources — if you don't know what all of those are, for now, just think: Resource = Document). If you are used to Evolution permissions, however, you need some information about Contexts, Roles, Access Policies, and Access Control Lists (ACLs).

In short, Access Policies are just lists of individual permissions (e.g. save_tv, edit_document, view_document, access_permissions, etc.) that allow a user to perform a specific action or see something in the Manager. Roles are names that are associated with Access Policies with an Authority Number (more on these later). ACLs are simply lists of access rules that tie User Groups to Resource Groups and/or Contexts and to Policies. Let's look at those concepts in more detail:

Contexts

Contexts are a new concept in MODx Revolution and have many uses beyond the scope of this page. For our purposes here, we'll assume that you only have two Contexts, "web" and "mgr." The "mgr" Context is essentially the back end (MODx Manager). The web context is the front end (with a minor exception we'll get to later). If you create more Contexts later, everything you've learned here about the "web" Context will apply to them too.

By default, when you create Resources in the Manager, they will go below the "web" icon (unless you create other Contexts and place the resources in those Contexts). The Resources under the "web" icon are in the "web" Context. The "mgr" Context is simply the MODx manager. When Users are in the "mgr" Context, they are logged into the Manager. Permissions tied to the "mgr" Context determine what the user can do and see in the Manager. Permissions tied to the "web" Context limit what users can do or see in the front end of the site.

Roles

In MODx Evolution, when you create a Role, you define exactly which manager actions a user with that Role can perform. In MODx Revolution, however, the only things you set when you create a Role are the name of the Role, the Authority Number associated with that role, and an optional Description of the Role. The Authority Number of the admin Super User Role is 0. When you create other Roles, you will assign them higher Authority Numbers. The numbers are arbitrary numbers between 0 and 9999. All you really need to know about them for now, is that:

• Roles that are intended to have more rights attached to them should have lower Authority Numbers.
• You should generally avoid duplicate Authority Numbers.
• Users in a User Group will "inherit" the permissions given to Users with Roles that have higher Authority Numbers than their roles have.

That last rule means when editing a User Group's ACL entries, you should make sure that no specific Permissions are given to higher-numbered Roles that aren't already attached to Roles with lower numbers, because the Users with the lower-numbered Roles will inherit them even though they're not supposed to have them.

When you add a User to a User Group, you give the User a Role in the Group. You control what the User can and can’t do by creating an ACL entry for that User Group that specifies what Access Policy goes with that Role.

The only function of the Role is to assign that user an Authority Number (the one associated with the Role) in the group so that the User will inherit the Permissions of other Users in the group with greater Authority Numbers.

Roles are created by going to Security | Access Controls and selecting the "Roles" tab. Clicking on "Create New" button will create a new Role. Roles can be removed by right-clicking on them and selecting "Remove Role."

Access Policies

Access Policies are simply lists of individual Permissions. You can see a few of them (Important: don't edit or delete any of them now) by going to Security | Access Controls | Access Policies tab. Click on a Policy and select "Edit." Then click on the "Permissions" tab to see the list of Permissions for that Policy.

When an Access Policy is assigned (in an ACL entry — see below), Users are given all the Permissions listed in the Policy. If a User has conflicting Permissions (for example, the User belongs to two different groups and the "mgr" Context Permissions are different for that User) the most permissive rule will apply. So, if a user is granted a Permission in the "mgr" context in one place, no other rule in another place can take that permission away.

In the default Revolution install, two standard Policies are included: an Administrator Policy and a Resource Policy. Three important principles govern their use:

• Never edit the included Administrator or Resource Policies. Always duplicate them, then edit the duplicate.
• Policies used in Context Access ACL entries should be based on the standard Administrator Policy.
• Policies used in Resource Group Access ACL entries should be based on the standard Resource Policy.

Ultimately, there will be a description of each Permission included in the Permissions list in the Manager. For now, you can guess what each one does or see this page where most of the Administrator Permissions are described. You can also reach the official MODx documentation on security by clicking on the "Help" button on one of the security pages.

Access Control Lists

Note: Before messing with permissions, check the setting of the allow_root System Setting in System | System Settings. It determines whether users can create Documents in the site root and it overrides any other security settings. You can spend a lot of time trying to figure out why your users can't create documents if allow_root is set to "No."

Access Control Lists (ACLs) are lists of rules that connect User Groups to Resource Groups and/or Contexts. Every ACL entry has a Context and a Minimum Role. The Context specifies which Context the rule applies in. The "mgr" Context specifies that the rules will apply in the Manager. The "web" Context specifies that the rules will apply in the front end of the site. The Minimum Role determines which Users in the group the rule applies to.

One of the first stumbling blocks for new Revolution users is finding the ACLs. You reach them by going to Security | Access Controls | User Groups tab, right-clicking on a User Group, and selecting "Update User Group." The ACLs are available on the two right-hand tabs of the Update User Group panel. They appear as grids and, at present, the phrase "Access Control List" doesn't appear on the page. Every line in the grid is an ACL entry — a rule that specifies what users with a particular Role can do or see.

Note that it doesn't make sense to create an ACL entry until after you have created the User Group, Role, and Access Policy, that you will use in the ACL entry.

There are two kinds of ACLs: Context Access ACLs and Resource Group Access ACLs.

Context Access ACLs

Found on the "Context Access" tab of the Update User Group panel, the entries on this list control what administrative tasks Users can perform in the Context specified in the ACL entry. You create a new Context Access ACL entry by clicking on the "Add Context" button.

When a Context Access ACL entry is created, it "protects" the specified Context so that no users (including the Super User) will get access to that Context unless you explicitly give it to them in an ACL entry. If you create a new Context, for example, don't forget to give yourself access to it in a Context Access ACL entry for the Administrators user group (it will usually look just like the "web" ACL entry.)

In the Administrator User Group, there are already Context Access ACL entries for both the "mgr" and "web" Contexts. That makes those Contexts "protected" by default. This has a potentially confusing side effect: when you create a new User, that User won't be able to log in to the Manager until you put the User in a User Group and give the User access in a Context Access ACL entry for that User Group with a Context of "mgr." Once you've done that, the user can log in, but won't be able to see the "web" context in the Resource tree in the Manager until you give the User access to that Context in another Context Access ACL entry for the User Group with a "web" Context (this is the exception we mentioned earlier to the principle that the "web" context only effects the front end).

Every Context Access ACL Entry specifies a Context, a Minimum Role, and an Access Policy. Users with the Minimum Role in the User Group (or one with a lower Authority Number) will be able to perform all the administrative tasks in the specified Context that are listed in the specified Access Policy.

Let's say you have a User Group called SubAdmins and you want the Users in that group to be able to use the Manager, but with restricted capabilities. Here are the steps you would take:

• First, create a Role of SubAdmin with an authority level of 9.
• Create the SubAdmins User Group and add the Users to it with a Role of SubAdmin.
• Duplicate the standard Administrator Access Policy.
• Edit the duplicate and change the name to SubAdmin.
• On the Permissions tab, delete any Permissions you don't want your SubAdmins to have. Removing the access_permissions Permission will keep them from changing their own security level and those of other Users. Removing the element_tree and file_tree Permissions will prevent them from seeing those tabs in the left panel of the Manager. (Note: the element_tree and file_tree permissions are only available in the SVN and upcoming RC versions of Revolution.)
• Save the Policy
• Update the SubAdmins User Group by going to Security | Access Controls | User Groups tab, right-clicking on the SubAdmins Group and selecting "Update User Group."
• Go to the Context Access tab.
• Add an ACL entry (by clicking on the "Add Context" button). Give it the following:
• Context: mgr
• Minimum Role: SubAdmin
• Access Policy: SubAdmin
• Go to Security | Flush Permissions

If you quit now and log in as one of the SubAdmin Users, the login would be successful but the Resource tree at the left would be empty because we haven't given our SubAdmin users access to the "web" context. We need to create another Context Access ACL entry with the following:

• Context: web
• Minimum Role: SubAdmin
• Access Policy: SubAdmin

Now, our SubAdmins are real Manager users with restricted access to the Manager.

Note that we could have done this another way. We could have skipped creating the SubAdmin User Group and just added all our SubAdmin Users to the Administrator User Group with a Role of SubAdmin. Then, we'd have Updated the Administrator User Group and added the two Context Access ACL Entries listed above. The results would be the same and which way you do it is a matter of your overall Security strategy. If you will be restricting which Documents the SubAdmins can see, you'll probably want to create a separate User Group for them. If they will have access to all the Documents in the Manager, you might rather add them to the Administrator User Group.

Nothing you do in a Context Access ACL will affect which documents any user can see in the front end. That can only be done in a Resource Group Access ACL specifying a Context other than the "mgr" Context.

Resource Group Access ACLs

Found on the "Resource Group Access" tab of the Update User Group panel, the ACL entries on this list control which individual Resources users can see in the front and back ends, and what they can do with those Resources. You create a new Resource Group Access ACL by clicking on the "Add Resource Group" button. As with Context Access ACLs, once you create a Resource Group Access ACL entry, you have "protected" the Resources in the specified Context. No one can see them in that Context unless they are given access to them in a Resource Group Access ACL entry.

If you specify the "mgr" Context, the Resources in the Resource Group will only be visible in the Resource tree in the Manager to Users who have been given access to them. If you specify the "web" Context, only Users who have been given access to them (and are logged in) can see the Resources in the front end of the site.

These Resource Group Access ACL entries have the same fields as the Context Access ones with the addition of a field specifying the Resource Group.

Let's say you have a User Group called "Editors" and a Resource Group called "News" containing several news articles. You want to hide the news pages from non-Editor users in the Manager. You update the Editors User group to create a Resource Group Access ACL entry as follows:

• Resource Group: News
• Minimum Role: Editor
• Access Policy: Resource
• Context: mgr

Now only members of the Editors User Group with a Minimum Role of Editor (or a role with a higher Authority Number) can see the news pages in the Manager. They will have full rights to the resources. To limit them, you can duplicate the Resource Access Policy, change the name to "EditorResource," edit the duplicate to remove permissions you don't want them to have, and assign the EditorResource Policy in the ACL entry instead of the Resource policy.

As the admin Super User, when you Flush the Permissions (Security | Flush Permissions), you'll notice that the news pages disappear from the tree. To get them back, you'll either have to add the admin to the Editors user group (presumably with Minimum role of Super User and an Access Policy of Administrator) or update the Administrator User Group to add a Resource Group Access ACL entry specifying the News Resource Group, a Context of "mgr" and again a Minimum role of Super User and an Access Policy of Administrator.

The ACL entry above will protect the news pages in the Manager, but anyone can still see the pages in the front end of the site.

Let's say that you want to hide the news pages from anonymous users in the front end. Create another Resource Group Access ACL as follows:

• Resource Group: News
• Minimum Role: Editor
• Access Policy: Resource
• Context: web

Now, only members of the Editors group who are logged in in the front end can see the news pages. This ACL entry will protect the news pages in the front end, but will have no effect on who can see them in the Manager.

Note that when you preview Documents from the Manager, you are still logged in as the Super User. To test your front-end permissions, visit the site in another browser.

Controlling What Users Can Do and See in the Manager

What you want to do, in a nutshell, is to duplicate the standard administrator policy. Then put users in a user group and update that user group in Security -> Access Controls. Create a Context Access ACL entry for the mgr Context with the duplicate policy you created (and a role with a higher authority number than the Admin). Then edit the duplicate policy and remove any permissions you don't want them to have.

That will limit what the users can do in the Manager.

You can also put specific resources in Resource Groups and specific elements in Categories, then do something similar to the above, but duplicate the Resource policy (for resources) and the Element policy (for elements). You then create Resource Group Access ACL entries and Element Category Access ACL entries with the two respective policies and edit the policies to remove permissions as above. That will limit what users can do with the specific objects in the resource group or element category.

You can also do a lot by just customizing the Manager. You can hide parts of the various forms using Form Customization. Hide parts of the Resource tree by setting a tree_root_id user setting. Hide parts of the File tree with a filemanager_path user setting. Hide the Element tree and File tree altogether by removing the element_tree and file_tree permissions in the duplicate admin policy. Use custom permissions to hide various Top Menu items and subitems.

Manager Actions in the Front End

If you don't have snippets or plugins that perform Manager actions when a page is visited in the front end, such as clearing the cache or changing security settings, you don't need to worry about this section. Most regular snippets (e.g. Wayfinder, BreadCrumbs, and most custom snippets) will execute fine. All code will also execute if you are previewing the page from the Manager as the admin Super User.

Remember, though, that by default the "web" Context is protected by the ACL entry in the Administrator User Group. Users in the front end who are logged in, will need to be given the proper Permissions with a "web" Context Access ACL for their User Group in order for code that performs Manager actions to execute. It still won't execute for anonymous (not-logged-in) Users unless you also create a Context Access ACL for the anonymous User Group giving them the appropriate permissions in the "web" context.

Unauthorized Versus Error Page

This is a change from MODx Evolution. In Revolution, if a web page is protected in the front end so that only logged-in users can see it, the default behavior is for anonymous users to be redirected to the Error (page not found) page rather than the Unauthorized page when they try to access the resource. In Revolution, if Users don't have the "load" permission for a resource, it's as if it doesn't exist — thus the "page not found" response. If you would like them to be sent to the Unauthorized page instead, you can do the following:

• Create a new Resource Group Access ACL entry for the Anonymous User Group with the Resource Group of the protected resources, a Context of "web," a Role of "Member" and an Access Policy of "Load Only." Do this for each protected Resource Group

Note that this won't solve the problem for users who are logged on in the front end but are trying to access pages they are not authorized to see. To solve it for those users, add them to the user groups authorized to see the pages, but with a Role of "Member." Then, Update the user groups and add another Resource Group Access ACL entry for the group with the Resource Group set to the protected resources, a Minimum Role of "Member" and a policy of "Load Only."

Thank you for visiting BobsGuides.com

  —  Bob Ray