Composr Tutorial: Access control and privileges

Written by Philip Withnall (ocProducts)

Any large site will have areas that it wants certain members to be able to access, but not others. For example:

Categories of information that are visible to the eyes of members from only one usergroup
Pages available only if you're new to the site

Composr has a powerful access control and privilege system built into its core
For an overview of the Composr permission system, see the Advanced configuration tutorial. This tutorial goes into more detail.

Table of contents

Composr Tutorial: Access control and privileges

Brief overview of what can be set

You can set:

Access (view) permissions for zones, pages, and categories.
Global privileges.
Overridden privileges for particular content-types, by overriding them on the module (page) controlling that content-type.
Overridden privileges for particular categories.
Ad hoc access control on particular match-keys.

You cannot set:

Permissions on the entry-level (e.g. for a specific news article). You need to use categorisation to group entries that would have the same access level.
Write privileges on individual Comcode Pages. It is possible to set them on a per-zone basis though. You can also allow one particular user to have control over a particular page if they are the owner of that page (i.e. the submitter), and they have been granted permission to edit their own content.
Permissions on the member-level. You need to use usergroups to assign permissions. You can put members in multiple usergroups to achieve complex permission schemes. Technically Composr does support per-member permissions, but we don't have a user interface to set it because we wanted to keep the system concepts as streamlined and simple as possible: usergroups always provide a way to achieve what is needed.
Inheritable permissions from parent to child categories. You can quickly copy permissions to subcategories in the Permissions Tree Editor instead, or assign them at the module level and leave the categories as non-overridden (so inheriting from module to all categories within that module). We made this decision for simplicity and performance reasons.
Per-field (i.e. sub-entry) edit permissions.

Access (view) control

To edit permissions in Composr you can either use:

The Permissions Tree Editor
Disparate configuration (described in sections below)

The Permissions Tree Editor allows you to see and set permissions for all site structure and content from a single user-friendly interface. It is designed to allow quick setting of permissions without having to trawl through a different screen for everything being worked with.

Access the Permissions Tree Editor from:
Admin Zone > Security > Permissions Tree Editor

Another feature of the Permissions Tree Editor is the ability to make batch selections and apply permissions to everything selected. You can do this in the conventional way using the Ctrl/Shift keys (Option/Shift keys on a mac).

Note that the Sitemap shown in the Permissions Tree Editor depends on the "Single public zone" configuration option.
If this option is on then the default content pages will be under the Welcome zone, and no Site zone will be shown. The Sitemap will start from Root.
If this option is off then the default content pages will be under the Site zone. Because the Welcome zone is almost empty the Sitemap will start from the Welcome zone.

The remainder details the separate permission setting interfaces in different parts of Composr. The concepts from below are relevant to using the Permissions Tree Editor, as they detail what controls are embedded at different points within the tree. We do recommend using the Permissions Tree Editor directly though, unless you happen to be working directly with the zone/category/page at the time of setting permissions for it.

Editing zone permissions

This section describes editing from outside the Permissions Tree Editor. It is easier to centralise control from the Permissions Tree Editor where all the settings here may be accessed.

You can edit zone permissions by editing the zone for which you want to change the permissions.

For each zone you can set which usergroups can access (view) it.

Go to Admin Zone > Structure > Zones. Choose a zone to edit (bear in mind that you can't change permissions for the Welcome Zone, as everybody is allowed to access it), and continue.

You will be presented with the zone editing form. Near the bottom are the options for usergroup access permissions: one binary 'can/can't' access permission per usergroup. Toggle the checkboxes as you see fit (if a checkbox is unchecked, the corresponding usergroup can't enter the zone, but if it is checked, the usergroup can enter the zone without problem), and submit the form.

Editing page permissions

This section describes editing from outside the Permissions Tree Editor. It is easier to centralise control from the Permissions Tree Editor where all the settings here may be accessed. In fact, we do not link the Page Permissions interface into the default admin menu structure unless JavaScript is not enabled. There is a similar interface when editing a Comcode Page, however.

For each page you can set which usergroups can access (view) it. For modules you can also often override certain privileges for the content handled within those modules.

Go to Admin Zone > Structure > Permissions. Choose 'Page permissions'. To edit a page's permissions manually, you need to go to the page permissions page. Once more, choose a zone to edit, and submit the form. You will be presented with a checkbox-grid of the permissions for every page in your selected zone. Along the top are the names of all the usergroups on your site, and down the side are the names of all the pages in your selected zone. In the middle is a checkbox-grid for the permissions, and down the right is a column of buttons for inverting a whole row of checkboxes at once (image).

Once all the access permissions are set as appropriate, submit the form.

Page permissions as a routine process

Composr routinely checks page permissions when choosing whether to include standardised links.

The best example of this would be when viewing someone's member profile. The member profile includes links to all kinds of screens relating to the member being viewed. However, these links are only included if the viewing user (not the member being viewed) has access to the pages involved. For example, if there is no permission to the contact_member page then no contact link will be given.

Editing category permissions

This section describes editing from outside the Permissions Tree Editor. It is perhaps easier to centralise control from the Permissions Tree Editor. All the settings described here are also present in the Permissions Tree Editor.

For each category you can set which usergroups can access (view) it, and often also override certain privileges for that category.

Usergroup access permissions exist for just about any type of category Composr provides: from calendar entry types to news categories, you can easily set the usergroup access permissions through the category edit page. In this example, we'll change the usergroup access permissions for a news category.

Go to the Content Management Zone. Choose the icon for the content type you want to edit. Click the 'Edit one category' icon. Select the category to edit, and submit the form.

Then, set the permissions as necessary, and submit the form once more.

The process is the same for editing the permissions of any type of category.

Privileges

Privileges – rather than controlling access permissions, control whether somebody is allowed to do something more specific, such as use high-level Comcode, or bypass the word-filter. Think of them as 'privileges'.

The privileges are managed from:
Admin Zone > Security > Privileges
You'll see a list of permission sections – all the privileges are grouped into related sections for ease-of-configuration. Choose a section, and submit the form to see and change the related privileges. The page shows a checkbox-grid of the usergroups and the privileges in your selected section. Set up the privileges as appropriate, and submit the form to change them.

For a good real-world example of how to set up privileges, see the 'Setting bypass-validation access' section of the organising discussion forums tutorial.

Adding, Editing and Deleting content

To submit/edit/delete you need the correct privileges. You also need view permission all the way to the page that does it, in the CMS zone.

Here is a worked example of how to set view and privilege permissions to submit to a links catalogue category.

As view permissions work on a basis of needing to get past successive barriers, you need to have view permissions assigned to all of the following barriers to submit:

CMS zone
cms_catalogues module (by default all pages have view access)

Of course, if you want people to be able to submit, you probably also want them to be able to view. You'd need view permissions assigned to all of the following barriers to view:

Site zone
catalogues module (by default all pages have view access)
Links catalogue
category

Privileges on the other hand are inherited all the way from the global privileges. You don't need to set them at all if they are set in the global privileges and you haven't set up any overrides. However you would be able to set overrides on the Links catalogue itself, and the particular category you might want to allow/disallow links to be submitted to, should you wish to have more fine-grained control.

Note that privileges are not inherited through category trees, so setting privileges on a parent category will not change privilege to the child categories. If you wanted whole subtrees of categories to have different privileges you'd need to use the batch selection feature in the Permissions tree editor. It is rare to want to be able to do this though.

Similarly, you do not need view permission on parent categories to view child categories, although it would be hard to find a category if you did not have access to view its parents.

Usergroup settings

Usergroups have a number of settings that are "privilege"-like. They're not actual privileges only because they aren't binary on/off, they take a value. This includes maximum post lengths, upload/attachment quotas, avatar sizing, and flood control settings. These settings are accessed by adding/editing usergroups.

Testing access and privileges

To test access permissions and privileges, it's best to create a test member, or to assume the identity of an existing lower-ranking (non-administrator) member. In fact, if you are using Conversr then there's a default member named 'test' for you.

The 'SU' feature allows an administrator to quickly and easily assume the identity of somebody else ("masquerade"), for whatever purposes he sees fit (and not needing to type in their password, or logout).

To use 'SU', simply enter the username of the member whose identity you would like to assume into the 'SU' box (in the footer), and press the enter/return key. A new window will open, presenting the same screen as seen by the specified user.
This works on the default theme. Custom themes may not have this in the theme footer. In that case you can access it by putting &keep_su=<username>/?keep_su=<username> onto the end of the URL as appropriate (e.g. http://yourbaseurl/index.php?keep_su=test to masquerade as the test user looking at your front page).

You can navigate around as the user, experiencing the site through his/her eyes (so to speak), as all the permissions are as they are for this normal user. This can easily and effectively be used to test out permissions changes to make sure they are as required.

You can use Guest as a username to act as if you are not logged in.

Please note that when using 'SU':

the member will not show as being 'online' in most contexts
(by design) you will still be able to:
- access a closed site
- view stack traces
- view permission diagnostics using FirePHP (FirePHP is explained below)
- access testing mode in the eCommerce system
- use page rendering tools (by typing in the URL only)
- show search engine queries

Debugging permission problems

FirePHP

Composr has a special feature to help you diagnose problems with your permission settings.

To use this feature you are best using Google Chrome and have the FirePHP4Chrome addon installed
Using an admin login, bring up your website and add &keep_firephp=1&keep_su=test to the end of the URL (change test to the username you want to test with)
You should find messages added to Chrome's Console (find it @ View → Developer → JavaScript Console)

By looking to see what permission checks pass or fail you can work out what settings you might want to change.

There are FirePHP equivalents in other browsers, but for simplicity we have focused the above instructions on the official/original Firefox addon.

Logging

As an alternative to FirePHP, you can create an empty writable data_custom/permissioncheckslog.php file. All failed permission checks will be logged to it.

Just don't leave the file there or it'll get very big, very fast!

Refreshing forms

Be aware that privilege changes may require refreshing of any currently-open forms where the privilege may be used.
For example, bypass-validation privileges add a checkbox to the form, and if the privilege is not enabled that checkbox will not be there. When the form is submitted Composr requires that checkbox to be checked, in addition to the secure re-testing of access that will happen automatically at this point.

Adding a new usergroup to a third-party forum

If you are using Conversr (you almost certainly are), ignore this section

If you are not using Conversr and decide to add a new usergroup, then Composr will not have any permissions associated with it.

Fortunately Composr has a special feature for this situation: go to Admin Zone > Security > Absorb usergroup-permissions. You may use this feature to take the permissions of an existing usergroup and copy them so that the new usergroup has those same permissions.

Concepts

Access permission: Whether members of a certain usergroup have permission to access somewhere (a zone, page, or category, for example); a member does not need all their usergroups to have access, only one
Privilege: Whether a certain usergroup has permission to do specific things (such as using high-level Comcode, or bypass the word-filter)
SU: Named after the Unix command 'SU' (superuser / switch user), which when used at the command line allows somebody to temporarily log in as a different user
Permissions Tree Editor: This editor is a user friendly interface for editing all permissions (except privileges) on a Composr website

Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.