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