Bob's Guides

MODx Evolution Permissions

Permissions can be a confusing issue in MODX. Many people are thrown by the separation between Manager Users and Web Users. (Note that this distinction goes away in MODX Revolution — where there are just "users".) The following information is for MODX Evolution and earlier. Security in MODX Revolution is a whole other ballgame. There is some information on Revolution permissions here.

In MODX Evolution, Manager Users include anyone who logs in via yoursite.com/manager and works in the MODX Manager (back end). Web Users, on the other hand, log in through a form in the front end of the site and never see the Manager. The main use of Manager User status is to control which documents those users can edit in the MODX Manager (back end). The main use of Web User status is to control which pages visitors can see when they visit the public part of the site (front end).

It's important to remember that Manager permissions have no effect on what people can see in the front end of the site and Web permissions have no effect on which pages Manager Users can access. (Special thanks are due here to Susan Ottwell for teaching me most of what I know about MODX permissions.)

The basic rule of MODX permissions is really pretty simple: When a document is assigned to a document group and that document group is linked to a user group, only members of that group can access the document.

Say, for example, you have a document called "News." In the Manager Permissions section of the Manager, you assign the "News" document to a Document Group called "General Editables." Now, still in Manager Permissions, you link the General Editables Document Group to a Manager User Group called "Editors." Now, only Manager Users who belong to the group Editors can see and edit the "News" document in the Manager. This won't have any effect on who can see the document in the front end.

Similarly, imagine that you have a document called "MemberList" and, in the Web Permissions section of the Manager, you assign the MemberList document to a Document Group called "MemberOnly" Now, still in Web Permissions, you link the MemberOnly Document Group to a Web User Group called "members." Now, visitors to your site can't see the MemberList page unless they are logged in and belong to the members Web User Group. This will have no effect on which Manager Users can see and edit the document in the Manager.

Planning Your Permission System

It is by far the best practice to design your entire permission structure before creating any pages at your site. That way, the system will be correct and complete and the document group checkboxes will be there when you create each page. Sadly, not many people do it this way. For those who do, here's a brief guide to planning a permission system for MODX. There's no requirement that you follow the guidelines here, but they have worked well for me. It works best if you complete all the following steps on paper before implementing anything in MODX.

It's usually best to start with the Manager permissions. It's often easier and it doesn't affect anything in the front end of your site.

1. Make a list of all your possible documents.
2. Make a list of all Manager User Groups you'll need, based on who should access various sets of documents in the Manager. It's fine if the groups overlap and a document will be accessible to more than one group (in fact, it's fairly common). It's also fine if a "group" has only one member.
3. Documents that should be accessible to all Managers should be assigned to no group.
4. Name each Manager User Group with a descriptive name. Use a prefix like mug to remind you that it's a Manager User Group (e.g. mugEditors).
5. Make a list of all the Manager Document Groups you'll need. For each Manager User Group, you'll need a corresponding document group that members of that group can access.
6. Name each Document Group with a descriptive name. For documents that will be accessible only to managers (i.e. they won't be seen at all in the front end of the site), use a prefix like md (for Manager Document) or mo (Managers Only). For the rest of the groups, many people use a prefix like mdg (Manager Docuement Group). These names will normally be related to the User Group Names (e.g. documents groups that will be available to mugEditors can be called mdgEditors)
7. Now make a list of Manager User Group/Manager Document Group links. In other words, which document groups go with which user groups. If the names are related, this will be easy.

Now that we have all the Manager permissions done. It's time to do the Web permissions. Basically, it involves the same steps. At this point, some people like to implement and test the Manager permissions before working on the Web permissions. I usually like to do them all on paper first. How you do it is, of course, up to you.

1. Use your list of all your possible documents.
2. Make a list of all Web User Groups you'll need, based on who should see the various sets of documents in the front end. It's fine if the groups overlap and a document will be accessible to more than one group (in fact, it's fairly common). It's also fine if a "group" has only one member. Remember that front-end users will only see documents that belong to a group if they are logged in and are members of the appropriate Web User Group.
3. Documents that should be accessible to all visitors, logged in or not, should be assigned to no group.
4. Name each Web User Group with a descriptive name. Use a prefix like wug to remind you that it's a Web User Group (e.g. wugMembers).
5. Make a list of all the Web Document Groups you'll need. For each Web User Group, you'll need a corresponding document group that members of that group can access.
6. Name each Document Group with a descriptive name. Many people use a prefix like wdg (Web Document Group). These names will normally be related to the User Group Names (e.g. a documents group that will be available to wugMembers can be called wdgMembers)
7. Now make a list of Web User Group/Web Document Group links. In other words, which document groups go with which user groups. If the names are related, this will be easy.

Now it's time to implement our permission structure. There's an excellent tutorial on creating Permissions in the Manager here. If you have already created the documents and need to create or change the permissions for them, an excellent tool is the Doc Manager module, available from the Modules tab in the MODX Manager. Select Doc Manager on that tab, then select the Permissions tab on the right.

1. Create your Manager User Groups (Security | Manager Permissions | User Groups).
2. Add the appropriate users to the Manager User Groups (Security | Manager Permissions | Manager Users | New User). Scroll to the bottom to assign each user to their groups.
3. Create your document groups (Security | Manager Permissions | Document Groups).
4. If the documents have already been created, write the document ID numbers on your paper list of documents. Then, use the Doc Manager module to add the documents to the appropriate groups. Or, you can edit each document and scroll down to the bottom to select the groups it should belong to.
5. Remember not to assign documents to any group if you want them to be accessible to any Manager User.
6. Set the User Group/Document Group links ((Security | Manager Permissions | User/Document group links). For each User Group, add the appropriate Document Group(s) by selecting them in the drop-down list at the right and clicking on the Add button.

Now, we'll do the same for the Web permissions.

1. Create your Web User Groups (Security | Web Permissions | Web User Groups).
2. Add the appropriate users to the Web User Groups (Security | Web Permissions | Web Users | New User). Scroll to the bottom to assign each user to their groups.
3. Create your document groups (Security | Web Permissions | Document Groups).
4. If the documents have already been created, write the document ID numbers on you paper list of documents. Then, use the Doc Manager module to add the documents to the appropriate groups. Or, you can edit each document and scroll down to the bottom to select the groups it should belong to.
5. Remember not to assign documents that should be accessible in the front end to any visitor to the site to any group.
6. Set the User Group/Document Group links ((Security | Web Permissions | User/Document group links). For each User Group, add the appropriate Document Group(s) by selecting them in the drop-down list at the right and clicking on the Add button.

Now test your permission structure to make sure that Manager Users, Web Users, and general visitors can see (and not see) the appropriate documents. Remember that when you are logged in as a Manager and use the "preview" feature of the Manager, you're still a manager so it's a good idea to have the site open in another browser where you are not logged in as a manager while testing. It's also a good idea to clear the site cache after making changes to the permissions. In some cases, you may have to clear your browser cache as well.

Document Permission Rules

Here's a more complete explanation of the MODX document permission rules (thanks again to Susan Ottwell for much of this information) and some examples showing how they work.

1. Any document that is not assigned to a document group is open for everyone.
2. A document in a document group that is not connected to a user group is open for everyone.
3. As soon as a document is assigned to a document group that is connected to a user group, it can only be accessed by users belonging to that user group.
4. The above rules apply to both Manager User permissions and Web User permissions, BUT:
5. Manager User permissions (which apply in the Manager) and Web User permissions (which apply in the front-end) are entirely separate.
6. Setting Manager User permissions has no effect on Web Users and vice versa.
7. The same document group can be connected to either or both, however.

Examples

Imagine this document and user group scenario:

Manager Users Groups

MugEditors

• Darlene
• Alfalfa

MugReviewers

• Spanky
• Buckwheat

Web User Groups

WugFans

• Happy
• Grumpy

WugNewbies

• Doc
• Sleepy

WugNobody

• (no members)

Document Groups

• NewsBriefs -- assigned to no user group
• Reviews -- assigned to MugReviewers, WugFans
• Events -- assigned to MugEditors, WugFans
• Gossip -- assigned to MugEditors, MugReviewers
• FanOnly -- assigned to MugEditors, WugFans
• Ed-Private -- assigned to MugEditors, WugNobody
• Rev-Private -- assigned to MugReviewers, WugNobody
• ManagerOnly -- assigned to WugNobody
• NewbieOnly -- assigned to WugNewbies

Documents

• Doc1 -- assigned to no document group (accessible to: anyone, front or back end)
• Doc2 -- assigned to NewsBriefs (accessible to: anyone, front or back end -- not assigned to a doc. group)
• Doc3 -- assigned to Reviews (accessible to: Spanky, Buckwheat [back end[, Happy, Grumpy [front end[
• Doc4 -- assigned to Events (accessible to: Darlene, Alfalfa [back end], Happy, Grumpy [front end])
• Doc5 -- assigned to Gossip (accessible to: Darlene, Alfalfa, Spanky, Buckwheat [back end], all front-end users)
• Doc6 -- assigned to FanOnly (accessible to: Darlene, Alfalfa [back end], Happy Grumpy [front end])
• Doc7 -- assigned to Ed-Private (accessible to: Darlene, Alfalfa [back end], no front-end users)
• Doc8 -- assigned to Rev-Private (accessible to: Spanky, Buckwheat [back end], no front-end users)
• Doc9 -- assigned to Ed-Private, Rev-Private (accessible to: Darlene, Alfalfa, Spanky, Buckwheat [back end], no front-end users)
• Doc10 -- assigned to ManagerOnly (accessible to: all Manager Users, no front-end users)
• Doc11 -- assigned to NewbieOnly (accessible to: all Manager Users, plus Doc and Sleepy [front end])

Note that in this setup, the Manager Users would not see many of the documents in the front-end when not logged into the Manager unless added to the appropriate Web User groups and logged in as Web Users.

Security Resources at Bob's Guides

Copyright © 2011-2025
Bob Ray