\midcom_services_auth_acl

This class is responsible for ACL checks against classes and content objects.

Privilege definition

Privileges are represented by the class midcom_core_privilege and basically consist of three parts: Name, Assignee and Value:

The privilege name is a unique identifier for the privilege. The mRFC 15 defines the syntax to be $component:$name, where $component is either the name of the component or one of 'midgard' or 'midcom' for core privileges. Valid privilege names are for example 'net.nehmer.static:do_something' or 'midgard:update'.

The assignee is the entity to which the privilege applies, this can be one of several things, depending on where the privilege is taken into effect, I'll explain this below in more detail:

On content objects (generally every object in the system used during 'normal operation'):

• A Midgard User encapsulated by a midcom_core_user object.
• A Midgard Group encapsulated by a midcom_core_group object or subtype thereof.
• The magic assignee 'EVERYONE', which applies the privilege to every user unconditionally, even to unauthenticated users.
• The magic assignee 'USERS', which applies to all authenticated users.
• The magic assignee 'ANONYMOUS, which applies to all unauthenticated users.
• The magic assignee 'OWNER', which applies for all object owners.

On users and groups during authentication (when building the basic privilege set for the user, which applies generally):

• The magic string 'SELF', which denotes that the privilege is set for the user in general for every content object. SELF privileges may be restricted to a class by using the classname property available at both midcom_core_privilege and various DBA interface functions.

The value is one of MIDCOM_PRIVILEGE_ALLOW or MIDCOM_PRIVILEGE_DENY, which either grants or revokes a privilege. Be aware, that unsetting a privilege does not set it to MIDCOM_PRIVILEGE_DENY, but clears the entry completely, which means that the privilege value inherited from the parents is now in effect.

How are privileges read and merged

First, you have to understand, that there are actually three distinct sources where a privilege comes from: The systemwide defaults, the currently authenticated user and the content object which is being operated on. We'll look into this distinction first, before we get on to the order in which they are merged.

Systemwide default privileges

This is analogous to the MidCOM default configuration, they are taken into account globally to each and every check whether a privilege is granted. Whenever a privilege is defined, there is also a default value (either ALLOW or DENY) assigned to it. They serve as a basis for all privilege sets and ensure that there is a value set for all privileges.

These defaults are defined by the MidCOM core and the components respectively and are very restrictive, basically granting read-only access to all non sensitive information.

Currently, there is no way to influence these privileges unless you are a developer and writing new components.

Class specific, systemwide default privileges (for magic assignees only)

Often you want to have a number of default privileges for certain classes in general. For regular users/groups you can easily assign them to the corresponding users/groups, there is one special case which cannot be covered there at this time: You cannot set defaults applicable for the magic assignees EVERYONE, USERS and ANONYMOUS. This is normally only of interest for component authors, which want to have some special privileges assigned for their objects, where the global defaults do no longer suffice.

These privileges are queried using a static callback of the DBA classes in question, see the following example:

public function get_class_magic_default_privileges() { return Array ( 'EVERYONE' => [], 'ANONYMOUS' => [], 'USERS' => ['midcom:create' => MIDCOM_PRIVILEGE_ALLOW] ); }

See also the documentation of the $_default_magic_class_privileges member for further details.

User / Group specific privileges

This kind of privileges are rights, assigned directly to a user. Similar to the systemwide defaults, they too apply to any operation done by the user / group respectively throughout the system. The magic assignee SELF is used to denote such privileges, which can obviously only be assigned to users or groups. These privileges are loaded at the time of user authentication only.

You should use these privileges carefully, due to their global nature. If you assign the privilege midgard:delete to a user, this means that the user can now delete all objects he can read, unless there are again restricting privileges set to content objects.

To be more flexible in the control over the top level objects, you may add a classname which restricts the validity of the privilege to a class and all of its descendants.

Content object privileges

This is the kind of privilege that will be used most often. They are associated with any content object in the system, and are read on every access to a content object. As you can see in the introduction, you have the most flexibility here.

The basic idea is that you can assign privileges based on the combination of users/groups and content objects. In other words, you can say the user x has the privilege midgard:update for this object (and its descendants) only. This works with groups as well.

The possible assignees here are either a user, a group or one of the magic assignees EVERYONE, USERS or ANONYMOUS, as outlined above.

Be aware, that persons and groups are treted as content objects when loaded from the database in a tool like org.openpsa.user, as the groups are not used for authentication but for regular site operation there. Therefore, the SELF privileges mentioned above are not taken into account when determining the content object privileges!

Privilege merging

This is where we get to the guts of privilege system, as this is not trivial (but nevertheless straight-forward I hope). The general idea is based on the scope of object a privilege applies:

System default privileges obviously have the largest scope, they apply to everyone. The next smaller scope are privileges which are assigned to groups in general, followed by privileges assigned directly to a user.

From this point on, the privileges of the content objects are next in line, starting at the top-level objects again (for example a root topic). The smallest scope finally then has the object that is being accessed itself.

Let us visualize this a bit:

^ larger scope     System default privileges
|                  Class specific magic assignee default privileges
|                  Root Midgard group
|                  ... more parent Midgard groups ...
|                  Direct Midgard group membership
|                  User
|                  SELF privileges limited to a class
|                  Root content object
|                  ... more parent objects ...
v smaller scope    Accessed content object

Privileges assigned to a specific user always override owner privileges; owner privileges are calculated on a per-content-object bases, and are merged just before the final user privileges are merged into the privilege set. It is of no importance from where you get ownership at that point.

Implementation notes: Internally, MidCOM separates the "user privilege set" which is everything down to the line User above, and the content object privileges, which constitutes the rest. This separation has been done for performance reasons, as the user's privileges are loaded immediately upon authentication of the user, and the privileges of the actual content objects are merged into this set then. Normally, this should be of no importance for ACL users, but it explains the more complex graph in the original mRFC.

Predefined Privileges

The MidCOM core defines a set of core privileges, which fall in two categories:

Midgard Core Privileges

These privileges are part of the MidCOM Database Abstraction layer (MidCOM DBA) and have been originally proposed by me in a mail to the Midgard developers list. Unless otherwise noted, all privileges are denied by default and no difference between owner and normal default privileges is made.

• midgard:read controls read access to the object, if denied, you cannot load the object from the database. This privilege is granted by default.
• midgard:update controls updating of objects. Be aware that you need to be able to read the object before updating it, it is granted by default only for owners.
• midgard:delete controls deletion of objects. Be aware that you need to be able to read the object before updating it, it is granted by default only for owners.
• midgard:create allows you to create new content objects as children on whatever content object that you have the create privilege for. This means that you can create an article if and only if you have create permission for either the parent article (if you create a so-called 'reply article') or the parent topic, it is granted by default only for owners.
• midgard:parameters allows the manipulation of parameters on the current object if and only if the user also has the midgard:update privilege on the object. This privileges is granted by default and covers the full set of parameter operations (create, update and delete).
• midgard:attachments is analogous to midgard:parameters but covers attachments instead and is also granted by default.
• midgard:autoserve_attachment controls whether an attachment may be autoserved using the midcom-serveattachmentguid handler. This is granted by default, allowing every attachment to be served using the default URL methods. Denying this right allows component authors to build more sophisticated access control restrictions to attachments.
• midgard:privileges allows the user to change the permissions on the objects they are granted for. You also need midgard:update and midgard:parameters to properly execute these operations.
• midgard:owner indicates that the user who has this privilege set is an owner of the given content object.

MidCOM Core Privileges

• midcom:approve grants the user the right to approve or unapprove objects.
• midcom:component_config grants the user access to configuration management system, it is granted by default only for owners.
• midcom:isonline is needed to see the online state of another user. It is not granted by default.

Assigning Privileges

You assign privileges by using the DBA set_privilege method, whose static implementation can be found in midcom_baseclasses_core_dbobject::set_privilege(). Here is a quick overview over that API, which naturally only works on MidCOM DBA level objects:

• TODO: Update with the set/unset call variants
• TODO: Add get_privilege

Array get_privileges();
midcom_core_privilege create_new_privilege_object($name, $assignee = null, $value = MIDCOM_PRIVILEGE_ALLOW)
boolean set_privilege(midcom_core_privilege $privilege);
boolean unset_all_privileges();
boolean unset_privilege(midcom_core_privilege $privilege);

These calls operate only on the privileges of the given object. They do not do any merging whatsoever, this is the job of the ACL framework itself (midcom_services_auth_acl).

Unsetting a privilege does not deny it, but clears the privilege specification on the current object and sets it to INHERIT internally. As you might have guessed, if you want to clear all privileges on a given object, call unset_all_privileges() on the DBA object in question.

See the documentation of the DBA layer for more information on these five calls.

Properties

Methods