Permissions for Modules

Authorization for Module Developers

Overview

The MDPro authorization system allows for fine-grained control over virtually all site objects. This document explains how to integrate MDPro authorization into your own modules.

Setting the Component Name

A component name uniquely defines an area of control within MDPro. As such, you should take care to choose your component name so that it does not clash with any other current component name, and that it is clear to site administrators which component controls your block when they want to put access control on it.

The component consists of three parts, separated by colon (:) signs. The first part should be the module name. The second part is currently reserved and should be left blank. The third part can be a sub-category of your module, if it is complex enough to warrant it (unless a module has a number of separate function areas this is unlikely).

Note that sometimes a component name is not necessary. A module that purely works with content from another part of the system will just use the component from that content. Also, a module designed to replace a standard module can keep the same component name as the original. This allows for drop-in replacement of modules with very little effort on the part of the site maintainer.

If your module is replacing a currently existing module then you need to set the component name. If your module is purely supplementing it you can leave your component setting blank.

Choosing an Instance Schema

The instance schema for your module defines the types of content-dependent information that are used for authorisation. The instance schema consists of three parts, separated by colon (:) signs. The parts are totally dependent on the functionality of the block, and will normally contain dynamic information.

As an example of an instance schema, your module might be a gallery of pictures, with pictures separated out under categories. In this case, a possible instance schema would be 'Picture name:Category name:Picture ID'

Note that all of the standard modules that come with MDProhave instance schemas already worked out, so if you are working with content that is integral to MDPro you must use these schemas. Failure to do this can cause confusion in the authorisation system.

Configuring Your Module for Authorisation

The first thing to do when you configure your module is to announce your instance schema. To do this, add a line similar to the following one to the Version.php file:

 pnSecAddSchema('Gallery::' , 'Picture name:Category name: Picture ID');

Next, you need to protect all operations with the relevant component, instance, and access levels. This is done through the pnSecAuthAction call.

pnSecAuthAction takes four parameters. These are:

   - realm: currently 0
   - component: described above
   - instance: described above
   - access level: minimum access level required for authorisation.  The access
     levels are as follows:

          ACCESS_NONE      No access
          ACCESS_OVERVIEW  Allowed to get an overview of the content
          ACCESS_READ      Allowed to read the content
          ACCESS_COMMENT   Allowed to comment on the content
          ACCESS_MODERATE  Allowed to moderate the content
          ACCESS_EDIT      Allowed to edit the content
          ACCESS_ADD       Allowed to add content
          ACCESS_DELETE    Allowed to delete content
          ACCESS_ADMIN     Full access

These access levels are cumulative. Hence, someone with edit access can also read, comment, and moderate.

For example, the Gallery module will authorise the display of a picture as follows:

if (pnSecAuthAction(0, "Gallery::", "$picname:$catname:$picid", ACCESS_READ)) {

    // Display picture

}

Checking Against Foreign Permissions

Your module might need to check against foreign components to ensure that it is providing the correct information. An example of this might be a module that lists a set of story types that a user might be interested in. The module would have to check against the 'Stories::' component for each story that it wished to show, to confirm that the user has suitable permissions to see it. Note that in these cases it is crucial that the module also checks against the correct instance each time.

Best Practices

   - always check for permissions whenever you need to.  Do not assume that a
     permission check on an earlier webpage means that the operation is
     allowed.  This ensures that things like subverted URLs cannot do any
     damage.

   - check early for a blanket permission.  If the user is not allowed to do
     anything with a module then find that out early and don't waste time
     generating information that doesn't get used.

   - use the instance information where appropriate.  This allows for much
     finer-grained control over the site's content by the administrator, and
     leads to a much more flexible system.

   - let the authorisation system decide.  If you are, for instance, displaying
     a link to an administrative module, ask the authorisation system for
     permission to display this based on the module you are linking to rather
     than your own module.

Example Modules

Most of the modules that come with the official MDPro system use this authorisation system. Probably the best example module to look at is News, which contains all of the elements discussed in this document. In addition, the Banners module has a more complex authorisation schema.