Module Grants

Last updated December 11, 2011. Created by RdeBoer on March 20, 2009.
Edited by webchick, markabur, quicksketch, dman. Log in to edit this page.

Module Grants raison d'etre is to allow modules that deal with unpublished content and fine-grained access control (aka "grants") to work in the expected fashion. It works particularly well in publication workflows and revision moderation. Check out the step-by-step tutorials for Revisioning.

The module ensures that access grants are tested for unpublished content just as they are for published content, so that using the Workflow module (or any other module that uses the node_access table) you can implement workflows that deal effectively with content moving from author via moderator to publisher BEFORE it is published (which is where it's needed most, once content is visible for all to see, it's a bit late to start a publication workflow process!).
Using Taxonomy Access Control Lite you can restrict access to content to user-defined "vocabularies" such as departments or regions. With Module Grants this will work for unpublished content just as it does for published content.
Moreover when Workflow and TAC-Lite are used together this module makes sure that the combination exhibits the expected behaviour: access is granted to content only when it is in the correct state AND of the appropriate vocabulary "term" (such as department, country, etc.).
The module achieves this by AND-ing rather than OR-ing the grants.
Module Grants comes bundled with the Module Grants Monitor submodule, which provides users with an optional new menu item, Accessible Content, that shows a list of all content accessible to the logged-in user based on the permissions and access grants as determined by enabled modules. This list may be filtered using a double row of tabs residing at the top of the page, see point 3a below.

Installation and configuration

1. Place the "module_grants" folder in your "sites/all/modules" directory.
2. Under Administer >> Site building >> Modules, enable Module Grants and optionally Module Grants Monitor (recommended). If you're prompted to also enable the submodules Node Tools or User Tools say 'yes'. The Smart Tabs module from the Smart menus, Smart tabs project is highly recommended to achieve more natural and convenient tab behaviour.
3a. Visit Administer >> User management >> Permissions. Make sure that roles that are meant to be able to view unpublished and not yet published content have one of the following permissions:
o "view revisions" (section "node module"), or
o "view any|all content-type content" (section "revisioning module", if Revisioning installed).
Make sure that the role of anonymous user does NOT have any of the above permissions.
3b. There's usually no need to tick "administer nodes" for any role, which is good because "administer nodes" equates to almost god-like powers that you wouldn't normally give to normal users.
4. If required, install and enable as many modules for content access control as you need for your situation. Typical examples are Taxonomy Access Control (or use TAC Lite) and Workflow.
5. Optional, but highly recommended, especially when using Revisioning. Under Administer >> User management >> Permissions, section "module_grants_monitor module" select for each role which filtering tab they will get to use. The permissions, which are in alphabetical rather than logical order, relate to two rows of tabs that appear on the Accessible content page. The first row of up to 4 tabs filter content the logged-in user
* created,
* modified,
* can edit,
* can view
The second row of up to 3 tabs further filter content according to it being
* published,
* not published (includes previously published as well as not yet published)
* either of the above (that is: no additional filtering is performed in addition to the upper tab)

NOTE 1: you must tick at least one permission box for each of the 2 rows (you'll get a warning if don't)
NOTE 2: these tick boxes only determine whether the role in question gets to see the tabs, they do not in any way affect access to content. So in that sense you can safely tick any or all of the tab boxes for all authenticated users. However you may not want to confuse certain roles with too many tabs and too much output.

Usage

Most of Module Grants's magic (i.e. applying access grants to unpublished content and making multiple content access modules work together) happens silently behind the screen. You don't have to switch anything on in addition to the above instructions, point 1-3.
As mentioned, if the submodule Module Grants Monitor is enabled a new navigation menu item, Accessible content, will be available to the administrator and to roles to which the administrator granted access as per the above section, point 5. The content shown under Accessible content reflects the access grants given to the logged-in user by the content access modules installed on your system.

For the experts

The multi-module access leniency toggle (Administer >> Site configuration >> Module grants) was introduced to make the operation of multiple content access control modules together even more natural, especially when on the same site some content types are involved in workflow and/or taxonomies while other content types are not.
This checkbox has an effect only when two or more content access modules are enabled and one of the modules makes no statement about a node being accessed. If this box is checked ("lenient", the default), then a content access module saying nothing (via the node_access table) about the node in question will be deemed to be ok with the user having access to it. If not checked ("strict"), then a module saying nothing will be taken as a "deny access".

As mentioned Module Grants does its best to work around a bug/quirk in core and will cover 99% or so of the use cases you are likely to come across. However, to really dot the i's and cross the t's and make access control work properly in 100% of the cases (well that's what we aim for), you need to add one line to the modules/node/node.module core module. This is a little inconvenient, because it means that some time in the future after you've deployed a new version of core on your system, you'll have to apply this patch again. Fortunately it's only one line. Inside the node_access() function, find the following lines (2014-2016 in Drupal 6.19)

An example of when this core hack is necessary is if one module is explicitly granting access to a particular operation, such as "edit", while another one is explicitly denying access, and you want to make sure the denying one wins.

Appendix: permissions & grants in content access operations

At the heart of content access in drupal lies the node_access() function of the node.module. It gets called for each of the various access operations (create, view, edit, delete) attempted on a piece of content (i.e. a node). There are two tiers of access control involved. I'll call them permissions and grants and promise to avoid speaking of granting permissions or permitting grants. For any user other than someone having the “administer nodes” permission the following apply (simplified):

1. core permissions: these are the role-based permissions that can be flicked on in the node module section of the User Management>>Permissions page; these include the edit/delete tick boxes for own or others' content (4 per content type); if a ticked box applies to the content in question, then access is given immediately
2. if none of the ticked boxes apply, then
   a. if the published-flag is set, access to content is as per the view/update/delete grants in the node_access table, which may be populated by any custom module
   b. if the published-flag is not set, then access is denied (except for the case of an author viewing their own content)

The first thing to notice about the above is that for any custom module to even get a look in, you must not tick any of the edit/delete boxes pertaining to the content types in question, as they'll allow access before the custom module is given a chance to decide what it wants to do.
Secondly, modules for fine-grained access control (such as Workflow Access, TAC, TAC-Lite) tend to rely on grants in the node_access table for their implementation and are therefore rendered impotent when dealing with unpublished content, because of the way node access is wired into the drupal core (point 2b). The behaviour in point 2 is due to what may be one of the most discussed single lines of code in the drupal community {1}, {2}. Several developers have suggested removing the dependency on the published flag and some have in fact done so in their own installations {2, #20, #6} by modifying the core node module. However this requires you to make the same modification again every time a new drupal version comes out. Unknown side effects could pop up too {2, #21}. We felt it to be preferable to develop a custom module that doesn't require any core code to be patched, which is what we did in introducing the Module Grants module.

Finally, it should be noted that when multiple modules record grants in the node_access table, the node_access() function ORs (rather than ANDs) the module grants together. This is usually fine within a module, but when combining grants from two or more modules AND-ing them together often makes for more natural behaviour. OR-ing the grants has the undesirable effect of one module re-opening the door to content when access was already denied by another. For instance, when Taxonomy Access Control (Lite) is installed and an "entertainment" author can't view, say, a sports article because they don't have access to the “sports” term, then it would be wrong if after installing the Workflow module the author suddenly does have access, when another user (eg a moderator) puts the content in the “editable” state (and by the workflow grants authors can access "editable" content). The Module Grants approach is therefore to AND grants across modules.

References

Drupal forum posts on this topic in the context of workflow, taxonomies and revision moderation
{1} #346021: workflow view/edit/delete permissions for roles & states not working, comments #7, #8, #14
{2} #156028: Workflow nodes must always be published for access controls to apply, comments #10, #20, #21
{3} #218755: Support revisions in different states, introduction and comment #9
{4} #372724: Workflow integration with revisions - states for revisions

Further reading

{5} Book: Pro drupal development, 2nd edition, p. 162
{6} Node access control in drupal