Making Member-Only Pages

Introduction¶

MODX Revolution uses a whole new set of security systems to allow you more flexibility while giving your users access (or denying) to Manager and Web resources. As there seems to be need for a proper tutorial to get you into the basics of working with this advanced system this document has been written.

It's common to have pages in the front end of a site that can only be seen by certain users. This tutorial describes how to do that in MODX Revolution. It assumes that you already know how to let users register and log in using the components in the Login package. The process described below will have no effect on which resources users can see or edit in the MODX Manager.

For those that are savvy enough, below follows a simple list to help you through the maze or to remind you how it works. If you need more information and would like some examples, scroll down to the related subsection below.

1. Create a Resource Group (Security -> Resource Groups -> Create Resource Group)
2. Link your member-only resource to the Resource Group. (By editing the resource, or by dragging them from the resource tree to the right)
3. Create a User Group (Security -> Access Controls -> User Groups -> New User Group)
4. Add a resource group entry on the Resource Group Access tab (context: web, minimum role: Member (9999), access policy: Resource)
5. Add users to the user group with the role of Member. (Security -> Manage Users)
6. Flush permissions (Security -> Flush Permissions) and try it in another browser (not just another browser window: another browser)

Access Wizard explanation (2.2.2 and later)¶

MODX 2.2.2 ships with an access wizard that simplifies this process. The step-by-step explanation is still valid, but the access wizard simplifies the process. You may wish to read both explanations to gain a better understanding of how each aspect of MODX's security system interacts.

1. Create a Resource Group¶

Go to Security -> Resouce Groups and click the Create Resource Group. A window similar to this should pop up:

Let's go over each section:

Great! We have a resource group and a user group created. We now need to add resources to the resource group and users to that user group and then we'll be laughing.

2. Add Resources to the Resource Group¶

We need to tell MODX with resource we want to protect. Let's stay on the same page from Step 1 (Security > Resource Groups). On the right, open up the web context to see all the pages on your site. Drag them from the column on the right into your resource group. Easy, right? An alternative is to go into each resource, go to the Resource Groups tab, and check the checkbox under the "Acces" column and the "Protected" row.

3. Add Users to the User Group¶

Okay, we've had enough of the Resource Group page. Go to Security > Access Controls. In the Users Groups tab, we can see a list of all of the user groups on our site. Right click on the "Protected" User group. Select "Add User to Group". For the "Name", select the user you want in the user group. For the Role, let's select "Member" for now. Roles define what an individual user can do within a user group, but we don't need that fine of control for this tutorial. Click Save.

It is important to realize that as soon as you have protected a resource by (1) assigning it to one or more resource groups and (2) linking the resource group to a user group using an access control, those pages will no longer show up for users that are not linked to the resource group. The default behavior in that case is displaying the 404-error page. If you would rather return the 401-error, you will need to give the anonymous user group "load" permission for the resource group. More about this in a later tutorial. At this moment in the tutorial, your page will not be visible as you have not yet added it to a user group.

We now have our resources in a resource group, and users in a user group. Done? Sorry, we have a few small things to do first. If you're following this tutorial and this is your first foray into MODX security, you will likely run into a small but important snag: the user group we created doesn't have context access to our front end context, web. In other words, if we could view that context, we could view those protected resources -- but we can't currently view that context. Let's give our user group permission to view that context.

4. Add Context Access to the User Group¶

Go to Security > Access Controls. Right click on the protected user group. Select "Update user group". Go to the Context Access tab. Click "Add Context". We are presented with a dialog such as the one below. Let's break it down:

Let's make one rule with "web", "Member - 9999", and "Load, List and View". If we want users to be able to view the MODX manager, we can add a second rule to give them access to the mgr context: "mgr", "Member - 9999", and "Administrator". All these users will have admin access. If you would prefer to limit their permissions, you could instead choose "Content Editor" or "Developer" for their access policies. Alternatively, you can make your own in Security > Access Policies if you want to be specific about what users can or can't do.

We now have users in a user group, resources in a resource group, and that user group can view the context. We're so close!

5. Flush Permissions¶

Before you can see a change, you need to reset / flush what your individual users can see and do. Go to Security > Flush Permissions. To test this in the front end, you must use a different browser. 90% of your grief will come from not testing in a different browser or flushing your permissions, so don't be lazy and open that second browser up. Congratulations, you now have members-only pages!

In some cases you may need to clear the site cache, specifically for the mgr (manager) context as elements and resources may cache their permissions.

Step-by-step explanation (pre-2.2.2)¶

If you're not quite as savvy, or would rather also know what happens when you set a certain permission or make an access entry, you might find this section interesting. As of 2.2.2, MODX ships with an Access Wizard and you might wish to start with that.

1. Create a Resource Group¶

A Resource Group is a collection of resources which you can link to user groups and access list entries. When you have created a resource group, you can easily classify pages to be only visible for certain user groups, or roles within user groups.

To create a resource group, navigate to Security -> Resource Groups and click on the Create Resource Group button. In the popup you are prompted to enter a name for the resource group. In the tutorial we expect you named it "Protected".

2. Link your member-only resource to the Resource Group¶

Now that you have a resource group, you should add resources to it. There are two ways to achieve this.

First of all, you can go to Security -> Resource Groups and drag resources from the right resource tree to the left resource groups ("Protected"). The second option is editing your resource, and ticking the right box on the "Access Permissions" tab.

3. Create a User Group¶

You have a resource group with resource applied to them, now you'll need to decide who will be able to view the resources. For this, we'll make a new user group.

To do this, go to Security -> Access Controls. On the (default) User Groups tab, click on the New User Group button. Choose a name for the group, and submit the form.

4. Add Resource Group access¶

Move on to the "Resource Group Access" tab. This tab defines the resource groups your user group has access to. Three out of four fields are similar to the Context Access groups, namely the Context, Minimum Role and Access Policy. A new one is Resource Group which, as you probably guessed, defines the resource group the user group can access.

The settings:

• Resource Group: whatever you named it, for example "Protected"
• Context: web
• Minimum role: Member (9999)
• Access Policy: Resource

It is important to realize that as soon as you have protected a resource by (1) assigning it to one or more resource groups and (2) linking the resource group to a user group using an access control, those pages will no longer show up for users that are not linked to the resource group. The default behavior in that case is displaying the 404-error page. If you would rather return the 401-error, you will need to give the anonymous user group "load" permission for the resource group. More about this in a later tutorial. At this moment in the tutorial, your page will not be visible as you have not yet added it to a user group.

5. Add users to the user group¶

Now add some users to the user group. You can do this by editing the user, or by going back to the Users tab and adding them from there. It will ask for the User Group, as well as the Role. As we assumed the Member role with an authority of 9999, you can simply use that one.

When using a websignup snippet, make sure it automatically puts them in the right user group.

6. Flush permissions¶

Now that all settings are done, you will need to flush permissions (Security -> Flush Permissions) before you will see an effect. Also make sure that, if you go to test it front-end, you use a different browser all together. Don't use a different tab or browser window, as it will still use your Manager login to check for permissions.

Please note that in some cases it is also necessary to clear the site cache, specifically for the mgr (manager) context, as elements and resources may cache their permissions.

Still can't get it to work?¶

Make sure you followed everything step by step and that you flushed permissions properly. If everything seems to be alright, check again and then go to the Forums to ask for help. If you think the tutorial is misleading or inaccurate, please visit the forum topic (linked below) and post about what is incorrect so it can be fixed.

See Also¶

Bob's permissions guide: http://bobsguides.com/revolution-permissions.html

Forum topic discussing this tutorial: https://forums.modx.com/index.php/topic,51259.0.html

Using the Login Snippet to set up a basic "Members Only" area: Login.Basic Setup

Security: Security