How permissions are calculated
A frequently asked question is, "What are my permissions in this context?". This article attempts to explain how Moodle answers that question. The article is written for non-programmers as well as programmers. It describes what the function does, not how it does it. If you are a programmer and want to see the how, look at the functions has_capability_in_accessdata and has_capability() in lib/accesslib.php.
Incidentally, you will be able generate permission tables like the ones in this article using the 'Explain' links on the new Check permissions page in Moodle 2.0. In earlier version, you can install the rolesdebug.php roles debugging script.
Clarifying the question
Let us refine the question "What are my permissions in this context?"
Naturally, my can be any user that Moodle knows about. If you don't specify a particular user, it will default to the currently logged in user.
Permissions can be broken down into a computed permissions of true or false for each capability. The different capabilities are completely independant (apart from the magic 'moodle/site:doanything' capability which will be explained later).
A context is a part of a Moodle site. For example a course, a course category, an activity, or so on. Contexts are nested, so an activity will be in a course, which will be in one or more categories, which will be in the whole system. The most specific context that you are in is the most important, and is the one that should be used when asking the question. The other, less-specific contexts that contain this one also influence the result.
So, while our original question was "What are my permissions in this context?" the question Moodle will answer is "Does user $user have capability $capability in context $context?" and the answer will be 'Yes' or 'No'.
The calculation
As explained in the previous section, we want to know whether has_capability($capability, $context, $user) returns true or false.
In order to calculate the answer, Moodle needs to combine various pieces of data.
Data used by the function
Relevant contexts
To simplify the explanation, let us work with a particular example. Suppose that user $user wants to reply to a forum post ($capability is 'mod/forum:replypost') in a particular forum. And suppose that the forum is in a course in Subcategory B which is in Category A in this Moodle site. That is, the relevant contexts are:
System
|
Category A
|
Subcategory B
|
Course
|
Forum <--- the user is here
Role assignments
All the roles that the user has been assigned in all the relevant contexts will influence the outcome of the has_capability question.
A natural example would be that a user has the role 'Student' assigned in context 'Course', and role 'Authenticated User' assigned in context System.
However, our example is going to be unnatural and complex, in order to demonstrate all the possible complexities. In our example the user has
- Role R1 in context System
- Roles R2 and R3 in context Subcategory B
- Roles R1 and R4 in context Forum
Role definitions
Naturally, the definition of each role affects the outcome of has_capability. (Role definitions are edited at Administration ► Users ► Permissions ► Define roles.) The role definition sets a permissions of 'Not set', 'Allow', 'Prevent' or 'Prohibit' for each capability.
As mentioned above, different capabilities are independent, so, for example, we only need to specify the settings for the 'mod/forum:replypost' capability.
- For role R1, 'mod/forum:replypost' is set to Allow.
- For roles R2 and R3, 'mod/forum:replypost' is Not set.
- For role R4, 'mod/forum:replypost' is set to Prevent.
Remember, this is an intentionally complex and unnatural example.
Permission overrides
In Moodle you can override the permissions for a role in a particular context. You can thing of that as changing the definition of the role in that context. An example would be "In this category of courses, we want to prevent students from posting to forums." In the absence of an override to a different permission, you can imagine that there is an override of 'Inherit' which means use the permission from higher up the chain of contexts.
In our ongoing example, we will assume the following overrides have been set up:
- In context Course,
- for role R2, the permissions for 'mod/forum:replypost' is overridden to Prevent
- for role R3, the permissions for 'mod/forum:replypost' is overridden to Allow.
Representing the data in tabular form
All the data mentioned in the previous section is best seen by writing it in a table.
In the table, there will be one row for each context, and at the start of each row, we write the name of the roles assigned in that context.
And there will also be one column for each context, and in that column we write any permission overrides for the roles in each row.
Except that in the column that represents the System context, we write the permissions from the role definition.
Normally, we think of contexts like folders in a file system, with the System context at the top, and the Forum context at the bottom. However, for this table, it turns out to be simpler later if we reverse the normal order, and put the Forum context in the first row and column, and the System context at the end.
The table for the example we have been building up looks like this:
The calculation
The calculation proceeds by working through the table in normal reading order, right to left, top to bottom. (That is why we put the Forum context first and the System context last.)
- First, look through the entire table and see if there are any Prohibit permissions anywhere. If there are, stop. The final answer is false - the user does not have this capability.
- If there are no Prohibits, start at the beginning of the first row with role assignments, and go along until you get to a cell containing 'Allow' and/or 'Prevent'. In this cell,
- If there are more Allows than Prevents, stop. The answer is true - the user has this capability.
- If there are more Prevents than Allows, stop. The answer is false - the user does not have this capability.
- If the number of Prevents and Allows is equal, jump down to the start of the next row with role assignments, and repeat this step 2.
- If you get to the end of the table without passing a cell with different numbers of Prevents and Allows, then the answer is false - the user does not have this capability.
Calculating the answer to our example
1. There are no Prohibits anywhere, so proceed to step 2. 2a. Work along the Forum row. We get to the last column. There are an equal number of Prevents and Allows here, so jump down to the start of the next row with role assignments. 2b. Work along the Subcategory B row. We get to the second column that corresponds to the overrides in the Course context. There are an equal number of Prevents and Allows here, so jump down to the start of the next row with role assignments. 2c. Work along the System context row. We get to the last column. There are more allows than prevents here, so the final answer is Yes, this user can reply to a post in this forum.
The path the algorithm takes is shown by the path in this diagram: File:role calc table1.png
Some variations to our example
TODO
Does this calculation make sense?
In almost every situation, the complex tie-breaking rules will not be required. Instead, the rules above will just calculate the answer you would expect if you don't think about it too deeply.
For example, you might be a student in a course and an Authenticated user in the System context. In that case, the calculation becomes:
- Does the student role actually determine the answer? That is, is there an override or does the role definition say whether this capability is Allowed or Prevented. If so, the most specific override gives the answer.
- Otherwise, is this allowed by the Authenticated user role?
Simple rules for using roles
If you follow the following guidelines, then the result of has_capability will always follow your intuitive expectations. (If you have a real-life situation where it is not possible to stick to these guidelines, then please post about it in the Roles and Capabilities forum.)
- When you define a role, just use permissions Allow or Not set (unless you actually need Prohibit).
- When you override permissions, only use permissions Allow and Prevent where you actually need them. Leave everything else set to inherit.
- Assign each user at most one role in each context (except, perhaps, in the System context).
When to use prohibit
Prohibit is designed for one particular situation.
Suppose a particular user has posted some inappropriate content in a forum. While you investigate what happened, and possibly for a disciplinary period after that, you want to prevent that user from posting anything else.
To do this, you create a special 'No posting' role, where a range of capabilities like mod/forum:replypost are set to Prohibit. Then you assign that role to that bad user in the system context. That will ensure that, no matter how the other roles are define, or what role overrides have been set, that user will not be able to post to any forums.
Some practical examples
TODO
See also
Forum threads:
