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.

Table of contents

ocPortal Tutorial: Access control and privileges

Access control

The Permission 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 of this section is concerned with manual permission setting.

Editing zone permissions

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

Setting zone permissions

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

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.

Choosing a zone to edit

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

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

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.

Choosing a category to edit

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.

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.

Specific permissions

Choosing a specific permission 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 specific-permissions are accessed through the "specific-permissions" page. On this page is a list of permission sections; all the specific-permissions are grouped into related sections for ease-of-configuration. Choose a section, and submit the form to see and change the related specific-permissions. The page shows a checkbox-grid of the usergroups and the specific access permissions in your selected section. Set up the specific-permissions as appropriate, and submit the form to change them.

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

Testing access and privileges

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

To test access permissions and specific permissions, 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.

Setting specific permissions

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 your personal statistics block), and click the 'Su' button. 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.

To use this feature you need to be using Firefox and have the Firebug and FirePHP addons installed
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)
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.

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.

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
specific permission: 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'), 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 specific permissions) on an ocPortal website