MODX: Permissions and Users

Contents

It is likely that you will need to provide different types of access to different types of users. Administrators will need full access to everything. Other users will need access to only certain parts of the site, and may need to be restricted in the kinds of actions they can perform.

Users

MODx has two types of users:

  1. Manager Users: the people who can use the MODx manager interface to create and edit content
  2. Web Users: the people who do not need manager access, but who need to log in to other features of the web site, such as for commenting on blogs.

This distinction will disappear in version 0.9.7 and up, but for now the distinction still exists.

To create a manager user

Go to Security > Manager Users, then click on “New user.”

Web Users

For now, this tutorial will not address web users. Most of the time these users will be created by a separate scrip—a blogging script, for example. As such, a full discussion of web users is beyond the scope of this particular tutorial.

Roles

Every manager user will have a role. The role determines the manager user’s global permissions within the MODx system. The role can grant or restrict access to perform functions related to content, template, snippets, user management, and so on. Every situation will have its own unique needs, but here are some suggested roles that will work in many situations:

  • Administrator: The default administrator account (this role cannot be edited or deleted)
  • Developer: Access to everything except user permissions, roles, and site configuration
  • Designer Plus: Access to content, files[note], templates, snippets, and chunks
  • Designer: Access to content, files[note], and templates
  • Editor: Access to content and files[note]
  • Proofreader: Ability to edit content, but not create or delete content, and no access to files.

Notes about files:

  1. To grant access to the file manager (to upload PDFs, Word documents, etc.), you need to scroll all the way to the bottom of the page to the “Configuration management” section and select “Use the file manager.”
  2. You can limit user access to subdirectories within the File Manager.

Important points about roles:

  • All manager users are assigned one and only one role. You cannot give a manager user more than one role, or no roles at all.
  • Roles do not control which web pages or sections of the site a user has access to. To do this, you must use group permissions.

To Create a Role

Go to Security > Roles > Create a new role. Check the boxes next to the permissions you want to grant.

To Assign a Manager User to a Role

Select the appropriate option from the “User’s role” drop-down box when creating or editing a user (Security > Manager Users).

Group Permissions

In MODx, the way to restrict who has access to which documents is done through group permissions. There are two types of groups:

  1. User groups
  2. Document groups

You have to create some of both for the system to work properly. At a minimum you have to create a user group, create a document group, then associate the two with each other. It is possible to assign multiple document groups to a single user group. It is not possible to assign multiple user groups to a single document group.

Example

Here’s a real world scenario. Let’s say you have 13 organizations that you want to publish information about on your web site: Organization A, Organization B, Organization C, and so on through Organization M. You want to grant access to certain people within each organization to edit their own web pages, but not the web pages of the other organizations. To make things more complicated, organizations A through F belong to Category 1, and the others belong to Category 2. You want to assign a group of “Category 1 managers” to oversee the web pages of all of the organizations in Category 1, and you want to assign a different group of “Category 2 managers” to oversee the web pages of the organizations in Category 2. On top of all of this, you have an “Organization Czar” who is in charge of overseeing all organizations in both categories.

Here’s how you could set this up:

  1. Create a user group for each organization. To make things simple, you could call the user groups “Organization A,” “Organization B,” and so on through “Organization M.”
  2. Create a document group for each organization. I would use the same naming convention (“Organization A,” “Organization B,” etc.).
  3. Create a user group called “Category 1,” and a user group called “Category 2.”
  4. Create a user group called “Organizations.”
  5. Associate the user groups with the appropriate document groups.
    • Associate the user groups for the individual organizations with only one document group, e.g. user group “Organization A” will be associated with document group “Organization A.”
    • Associate the user group “Category 1″ with all of the document groups for each of the organizations that belongs to Category 1. Organizations A through F belong to Category 1, so associate user group “Category 1″ with document groups “Organization A” through “Organization F.”
    • Associate the user group “Organizations” with each of the organization document groups.
  6. Assign users to the appropriate user group(s).
  7. Assign documents to the appropriate document group(s).

To create a User Group

Go to Security > Manager Permissions > User groups. Type a group name under “Create a new user group.” Click “Submit.”

To Create a Document Group

Go to Security > Manager Permissions > Document groups. Type a group name under “Create a new user group.” Click “Submit.”

To Link User Groups to Document Groups

Go to Security > Manager Permissions > User/Document group links. Select a document group name from the drop-down list of documents. Click “Add.” You may repeat this process to add multiple document groups to a single user group.

To Add a User to a User Group

Go to Security > Manager Users, then click on the user’s name (or click “New user”). Scroll down until you see “Access Permissions.” Select the appropriate user group(s). Note that you can’t add users to document groups, only to user groups.

To Add a Document to a Document Group

Click on the page in the Document Tree on the left, then click on “Edit” in the main view. Scroll to the bottom area of the screen until you see the “Access Permissions” list. Select the appropriate document group(s) from the list. Note that you can’t add a document to a user group, only to document groups.

Important points about group permissions:

  • Documents have no access restrictions by default. If documents are not assigned to a specific group, they are editable by all document groups. In most multi-user settings, this is a bad idea. Unless you are a small team of fully-privileged administrators who trust each other completely, you probably do not want any document to be completely editable by everyone. You should create groups and assign all pages to at least one group.
  • Users can access only those files assigned to their group. If a user is not assigned to a group, the user will be able to access only the documents marked for “All Document Groups (Public).” If all documents are assigned to a group (as they should be), this user would not be able to access any documents.
  • Documents inherit the permissions of their parent documents. By default, when you create a document, it will inherit the permissions of its parent document, which is a usually good thing… unless you realize after the fact that you forgot to assign the correct permissions to the parent document. Then you have to go back and manually associate each document with the appropriate group(s). It is especially important to set the correct permissions as you create pages on the root level of the site, because without any parent document to inherit from, they will be editable by all users by default, which, as I have mentioned before is probably a bad thing.

WARNING: Users must be granted permission to at least one document on the root level. Unfortunately, the permission system in MODx does not allow users to access subdirectories unless they can also access the parent document(s). If you don’t provide access at least one line of parent document(s) all the way up to the root level, the users will see an empty document tree, and they won’t be able to access anything. This is a flaw in MODx, because it means that users must be given full editing privileges to all parent documents in this path, even if you don’t want them to have this access. Using the example from above, if the path to the “Organization A” main page is /organizations/category1/organizationA/, you must designate the documents “organizations” and “category1″ as belonging to the document group “Organization A.” People belonging to the document group “Organization A” will be able to edit all of the pages underneath “organizationA”, as you would want and expect, but they will also be able to edit the parent documents “organizations” and “category1,” as perhaps you would not expect, and you certainly don’t want. But that’s the way it is. Currently there is no way to work around this flaw in MODx’s permission system.

Customizing Permissions to the File Manager

If you wisely decide that you do not want all of your users to have full access to all of the files in the file manager (the “assets” folder), you will need to restrict their access to a certain subdirectory within this folder. This sounds easy enough, and in some ways it is, but it is complicated by the way in which the file browser for MODx’s rich text editors works.

The principle is easy enough: to restrict a user to a certain directory in the file manager, set that user’s “File Manager Path” to a subdirectory within the “assets” folder. For example, if the default path to the file manager is “/home/web/public_html/assets/”[note] you could set the directory for a user in the “Organization A” group to something like “/home/web/public_html/assets/org_a/”. But you need to take into account other factors. If you want people in the user groups “Organizations” and “Category 1″ to also access this folder, you probably ought to put the path in a similar hierarchy. Something like this could work: “/home/web/public_html/assets/orgs/cat1/org_a/”.

Note: The default path for the File Manager is set in the site configuration under Tools > Configuration > File Manager > File Manager Path.

To customize the File Manager Path

Go to Security > Manager Users, click on the name of the user you want to edit (or select “New user”), then click on the “User” tab and type in the desired path for the “File Manager Path.”

  • Customizing the File Manager Path has no effect on the file browser from within the rich text editor. You must set that path separately (see customizing permissions to TinyMCE).

Customizing Permissions to TinyMCE

TinyMCE can be customized for each user, in terms of the interface and the file browser. The default settings for the site are available under Tools > Configuration > Interface and Features > TinyMCE Settings. To customize these settings for individual users, Go to Security > Manager Users, click on the name of the user you want to edit (or select “New user”), then click on the “User” tab and scroll down to the “Resource path” and “Resource URL” options.

Customizing the File Browser Folder

You probably want the path of the file manager to match the path of the file browser used within the rich TinyMCE text editor. The two paths you have to change are “Resource path” and “Resource URL.” Make the “Resource Path” the same as the “File Manager Path.” In our example, the path would be “/home/web/public_html/assets/orgs/cat1/org_a/”. For the “Resource URL, convert this path into the public URL of the web site: “http://your_web_site.com/home/web/public_html/assets/orgs/cat1/org_a/”.

Important: If you customize the path to the file browser, you will need to create two subfolders within this path: “images” and “files.” The file browser looks for all images within the folder called images, and looks for all files within the folder called “files.” If these folders don’t exist, users won’t be able to take advantage of the file browser. In our example, the folders will be found at these paths: “/home/web/public_html/assets/orgs/cat1/org_a/images/” and “/home/web/public_html/assets/orgs/cat1/org_a/files/”. You do NOT need to enter these paths anywhere in the configuration settings, but the folders must exist for the file browser to work.

Customizing the TinyMCE Interface

You do not have to customize the TinyMCE interface. If you leave all of the files under “TinyMCE Settings” blank, users will be given the default features as specified in the site settings (Tools > Configuration > Interface and Features > TinyMCE Settings). But you may decide that you want some users to have customized versions of the TinyMCE interface. There are preset “Themes” to choose from: Simple, Advanced, Content Editor, and Custom. Choose from among these options.

Setting the options for “Custom Plugins,” “Custom Buttons,” and “CSS Selectors” goes beyond the present scope of this tutorial, but I will mention one useful option: adding table editing controls. This should probably be done for all users, rather than just for certain ones. To add table editing options, type “tablecontrols” in Row 3 of the “Custom Buttons.” Scroll to the top and click “Save.”

WARNING: It is impossible to set a custom CSS file for each user. If you set a “Path to CSS file” in the site configuration (Tools > Configuration > Interface and Features > TinyMCE Settings), you are stuck with this style sheet no matter what, even on pages that don’t use it. This is a real shame, and severely limits the usefulness of the “Path to CSS file” option. One clumsy workaround is limit the number of classes available to TinyMCE by listing them in the site’s “CSS Selectors” option, and then ensure that all style sheets have all of these particular classes.