HTML Logo by World Wide Web Consortium ( Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS. ocPortal 9 is superseded by Composr 10.

Head over to for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.

ocPortal 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
ocPortal has a powerful access control and privilege system built into its core
For an overview of the ocPortal permission system, see the 'Advanced configuration' tutorial.

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.
  • Adhoc 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. In v10+ it will be possible to set them on a per-zone basis though. In any version you can 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 ocPortal 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.

Access (view) control

Thumbnail: The Permissions Tree Editor

The Permissions Tree Editor

To edit permissions in ocPortal you can either use:
  • The Permissions Tree Editor
  • Manual configuration

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 crawl through a different screen for everything being worked with.

The remainder details the separate permission setting interfaces in different parts of ocPortal. 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.

Thumbnail: Setting zone permissions

Setting zone permissions

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 the Admin Zone, then the 'Structure' section, then the 'Zones' icon. 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.

Thumbnail: Editing page permissions

Editing page permissions

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 the Admin Zone, then the 'Structure' section, then the 'Permissions' icon. 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 [Example ].

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

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.

Thumbnail: Editing category permissions

Editing category permissions

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 ocPortal 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.

Match-key permissions

For an explanation of match-key s, see the Customising what's on the menus tutorial.

Thumbnail: Here we have removed banner submission for guests. Normally we would restrict based on content visibility level, but that is less fine-grained.

Here we have removed banner submission for guests. Normally we would restrict based on content visibility level, but that is less fine-grained.

If it is not enough to specify whether a member can access a specific page based on the available view permissions and overridden privileges, you can also set things up to deny access to pages based on the URL parameters they are opened with. This could be used, for example, to allow members to browse through download categories but not actually view any download entry.
The match-key permission system is not intended to be used unless really needed - it is there to provide additional control when page and privileges won't meet your unique needs.

To add a new match-key permission, go to the "Match-key page restriction" icon in the Security section of the Admin Zone.

An example match-key that would deny access for viewing download entries would be: _WILD:downloads:type=view. Usergroups could be ticked (checked) to deny member's in those usergroups access to the website screen that actually views a download (type=entry is that interface).

At the bottom of the same screen you can choose what error message to display if someone is denied access. This is very useful if you have a specific reason for closing down access to something that you wish to explain.


Thumbnail: Choosing a privilege section to edit permissions within

Choosing a privilege section to edit permissions within

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 accessed through the "privileges" page. On this page is 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 page (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 page (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 Permission Tree Editor. It is rare to want to be able to do this though.

Similarly, you do not need view permissiosn on parent categories to view child categories, although it would be hard to find a category if you did not have access to view it's 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

Thumbnail: The SU feature is incredibly quick and easy: just enter a name and click a button

The SU feature is incredibly quick and easy: just enter a name and click a button

To test access permissions and privileges, it's best to create a test user, or to assume the identity of a lower-ranking (non-administrator) member. This section is concerned with the use of the 'su' function.

Thumbnail: Setting privileges

Setting privileges

The 'su' function allows an administrator to quickly and easily assume the identity of somebody else, for whatever nefarious or benevolent purposes he sees fit. To use 'su', simply enter the name 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. You can navigate around as this 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.

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, and view permission diagnostics using FirePHP

Debugging permission problems

ocPortal has a special feature to help you diagnose problems with your permission settings.
  1. To use this feature you need to be using Firefox and have the Firebug and FirePHP addons installed
  2. Once the addons are both installed, make sure that all the debugging panes (Console, HTML, CSS, Script, DOM, Net) for Firebug are enabled for your website (to bring up Firebug click the bug icon in the tray of icons in the bottom right of the browser)
  3. Bring up your website and add &keep_firephp=1 to the end of the URL
You will then find that details of all the permission checks, templates, and queries, used to generate the ocPortal screen are logged to the Firebug/FirePHP Console. By looking to see what permission checks pass or fail you can work out what settings you might want to change.

You can also create a writable data_custom/permissioncheckslog.php file, and 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 ocPortal 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 for a non-OCF site

If you are not using OCF and decide to add a new usergroup, then ocPortal will not have any permissions associated with it.
Fortunately ocPortal has a special feature for this situation: under the 'Security' section of the Admin Zone you will find an icon for it, '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.


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
Whether a certain usergroup has permission to do specific things (such as using high-level Comcode, or bypass the word-filter)
Named after the Unix command 'su' ('superuser'), 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 an ocPortal website

See also