Main Authentication/Authorization service class, it provides means to authenticate users and to check for permissions.

Unless further qualified, "Midgard Content Objects" can be either pre-mgdschema or mgdschema objects. The only neccessary constraint is that a MidCOM base class (midgard_baseclasses_database_*) must be available.

This implementation is based on the general idea outlined in mRFC 15 ( http://www.midgard-project.org/development/mrfc/0015.html ), MidCOM Authentication and Access Control service. Developers Note: Be aware that the basic requirements for the ACL system undergone a major chance during the implementation, as the DBA layer with full access control even for database I/O was added. The proposals from the mRFC are largly outdated therefore. What is documented on the main MidCOM documentation has to take priority obviously.

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 an 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 'de.linkm.taviewer: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 encaspulated by a midcom_core_user object.
• A Midgard Group encaspulated by a midcom_core_group object or subtype thereoff.
• 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 bothe midcom_core_privilege and various DBA interface functions.

The value is one of MIDCOM_PRIVILEGE_ALLOW or MIDCOM_PRIVLEGE_DENY, which either grants or revokes a privlege. Be aware, that unsetting a privilege does not set it to MIDCOM_PRIVLEGE_DENY, but clears the entry completly, 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 disctinct 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 wether 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 respectivly 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 obejcts, 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:

 function get_class_magic_default_privileges()
 {
     return Array (
         'EVERYONE' => Array(),
         'ANONYMOUS' => Array(),
         'USERS' => Array('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 respectivly 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 decendants.

Content object privileges

This is the kind of privilege that will be used most often. They are accociated 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 decendants) only. This works with (virtual) 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 Midgard Persons and Groups count as content object when loaded from the database in a tool like net.nemein.personell, 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 privileges, 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
 |                  Virtual group memberships
 |                  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 of the rest. This separation has been done for performance reasons, as the user's privileges are loade 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. They will move into the core level eventually, but for the time being MidCOM will control them. 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, and superseeds the current ViewerGroups implementation.
• 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 childs on whatever content object that you have the create privilege for. This means, 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-serveattachment 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 systems in AIS. Components implementing these screens must check this privilege manually, while the midcom_baseclasses_components_request_admin baseclass does this implicitly when accessing the config screen (you still need to control toolbar links yourself), 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.
• midcom:vgroup_register allows the user to add virtual groups to the system. This privilege is granted by default.
• midcom:vgroup_delete allows the user to delete virtual groups from the system. This privilege is granted by default.

DEPRECATION NOTE: The vgroup registering / deletion commands will be denied in the long run by default, for security reasons. Exact plan is not yet available though.

Assigning Privileges

You assign priviliges 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)
 bool set_privilege(midcom_core_privilege $privilege);
 bool unset_all_privileges();
 bool 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 auth framework itself (midcom_services_auth).

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.

Checking Privileges

This class overs various methods to verify the privilege state of a user, all of them prefixed with can_* for privileges and is_* for membership checks.

Each function is available in a simple check version, which returns true or false, and a require_* prefixed variant, which has no return value. The require variants of these calls instead check if the given condition is met, if yes, they return silently, otherwise they throw an access denied error.

Authentication

TODO: Fully document authentication.

Whenever the system successfully creates a new login session (during auth service startup), it checks whether the key midcom_services_auth_login_success_url is present in the HTTP Request data. If this is the case, it relocates to the URL given in it. This member isn't set by default in the MidCOM core, it is intended for custom authentication forms. The MidCOM relocate function is used to for relocation, thus you can take full advantage of the convenience functions in there. See midcom_application::relocate() for details.

Located in /midcom.core/midcom/services/auth.php (line 284)

PEAR
   |
   --midcom_baseclasses_core_object
      |
      --midcom_services_auth

Inherited Methods

Inherited From midcom_baseclasses_core_object

midcom_baseclasses_core_object::midcom_baseclasses_core_object()