Access Control Lists

TODO

• Explain exact configuration with content_acl and user_acl/user_profile_acl, etc.

Note: This page describes changes that have been done in the 2.0-storage development branch. This covers an unreleased version of MoinMoin! This page is not yet finished.

Note: We are talking about 'items' instead of 'pages' here because this concept has been redone in 2.0-storage. 'Pages' and 'Attachments' are now both 'Items'.

Access Control Lists (ACLs) can be used to give specific users or groups the right to do specific actions. They can be used to:

• hide items from the public.
• publish only some items to the public.
• give only somebody or a group write access to one or more items.
• give only certain users the privilege to create items.
• control who may change the admin rules for an item.

To use ACLs, you need either access to the wiki config (to set ACLs that are global within a backend) or the admin right on the specific item where you want to set (or change) ACLs.

Contents

Basics

The ACL rights available are:

• read - who may read an item.
• write - who may edit an item.
• create - who may create an item.
• admin - who may change the "acl" metadata for an item.
• destroy - special privilege that is given only to very trusted people, if anybody. It allows total erasure of an item (or a revision) and its history.

The current UI is tentative and will be redone properly. Using ACLs in moin is as easy as including a control line in the metadata-textbox of the item you want to control, like the following one:

acl: SomeUser:read,write All:read

• You need to already have admin rights to be able to add or modify such an acl line - see HelpOnConfiguration and HelpOnAutoAdmin.

This will allow SomeUser to read and write on that item, while every other user will be able to read but not edit it (unless you've done some special setup in the site configuration).

Configuration

There are different kinds of acl configuration options that can be tweaked on a per-backend level. These options are bound to their backend and need to be set for each individual backend, if required. Please refer to Storage2009/HelpOnStorageConfiguration for further reference on how to manually set up storage.

So you know now what it does, but what does it mean?

• "before" means forcing stuff (this is because of first match algorithm) Use this for your sitewide page admins or page editors.

• "default" means what is done if no ACLs are used on the item. It is equivalent to writing exactly these ACLs into an item's metadata. These are also the rights that are merged if Default is written among the ACLs for the item.

• "after" means not forgetting stuff accidentally (like maybe giving read rights to all)

It helps if you think of them as before, during, and after processing of item based ACLs.

That u"" notation used for the configuration strings means unicode and must be there - see HelpOnConfiguration for details.

Syntax

The syntax for acl lines is as follows:

acl: [+-]User[,SomeGroup,...]:[right[,right,...]] [[+-]OtherUser:...] [[+-]Trusted:...] [[+-]Known:...] [[+-]All:...] [Default]

Where:

• User is a user name and triggers only if the user matches.

• SomeGroup is a page name matching page_group_regex with some lines in the form " * Member" (see #Groups).

• Trusted is a special group containing all authenticated users of a trusted authentication method.

• Known is a special group containing all logged in users.

• All is a special group containing all users (known and anonymous users).

• Default is a special entry which inserts at the given place the entries from default (see #Default).

• right may be one of the following privileges: read, write, create, destroy, admin. Only words in acl_rights_valid are accepted, others are ignored. It is allowed to specify no rights, which means that no rights are given.

Do not put whitespace between the name and the rights - All: write,read is not a valid ACL string.

Available rights

These are the available rights you can use in an ACL entry.

read

Given users will be able to read content of this item.

write

Given users will be able to write (edit/modify) the content of this item.

create

Given users will be able to create new items.

admin

Given users will have admin rights for this item. It means users will be able to change ACL settings, including granting "admin" to others and revoking "admin" from others.

destroy

Given users will be able to completely erase an items revisions or even the item itself from storage (i.e., including history).

There is no separate rename right: renaming a page requires that a given user has the read and write rights on the item to be renamed and may create and write to the target name (i.e., the new name) of the renaming operation. There is no separate revert right: A revert operation will be successful if you can both, read and write the item in question. There is no separate delete right: You may delete an item if you are allowed to rename it to the trash namespace (i.e., you can read and write the item you want to delete and you can create and write in the trash namespace).

Processing logic on a single item

When some user tries to access some ACL-protected resource, the ACLs will be processed in the order they're found. The first ACL matching the user will tell if the user has access to that resource or not and processing will stop once the user matched an ACL entry.

Due to that first match algorithm, you should sort your ACLs: first single usernames, then special groups, then more general groups, then Known and at last All.

For example, the following ACL tells that SomeUser is able to read and write the resources protected by that ACL, while any member of SomeGroup (except SomeUser, if part of that group) may also admin it, and every other user is able to read it.

acl: SomeUser:read,write SomeGroup:read,write,admin All:read

To make the system more flexible, there are also two modifiers: the prefixes '+' and '-'. When they are used, processing will only stop when requested right for some specific user matches the user and right(s) in the given ACL entry, but will continue if you are looking for another right (or another user). In case of '+' the right will be given, in case of '-' the right will be denied (for the stopping case).

As an example, assuming that SomeUser is a member of SomeGroup, the above ACL could also be written as:

acl: -SomeUser:admin SomeGroup:read,write,admin All:read

This example is only special for SomeUser, because when admin right is queried for SomeUser, it will be denied and processing stops. In any other case, processing continues.

Or even:

acl: +All:read -SomeUser:admin SomeGroup:read,write,admin

+All:read means that when any user is requesting read right, it will be given and processing stops. In any other case, processing will continue. If admin right is queried for SomeUser, it will be denied and processing stops. In any other case, processing will continue. Finally if a member of SomeGroup is requesting some right it will be given if specified there and denied, if not. All other users have no other rights, except when given by configuration.

Notice that you probably won't want to use the second and third examples in ACL entries of some page. They're very useful on the site configuration entries though.

Inheriting from defaults

Sometimes it might be useful to give rights to someone without affecting the default rights too much. For example, let's suppose you have the following entries in your configuration:

default = u"TrustedGroup:read,write,create All:read"
before  = u"AdminGroup:admin,read,write,create +TrustedGroup:admin"

Now, you have some item where you want to give the "write" permission for SomeUser, but also want to keep the default behavior for All and TrustedGroup. You can easily do that using the Default entry:

acl: SomeUser:read,write Default

This will insert the entries from default in the exact place where the Default word is placed. In other words, the entry above, with the given configuration, is equivalent to the following entry:

acl: SomeUser:read,write TrustedGroup:read,write,create All:read

Lets look at the first example in this section:

before = u"AdminGroup:admin,read,write,create +TrustedGroup:admin"

ACLs are processed in the order of "before" then "page/default" and then "after", "left to right".

So it begins at the left of "before" with AdminGroup:... - this matches if you are a member of admin group. If it matches, you get those rights (arwdr) and ACL processing STOPS.

If it does not match, ACL processing continues with +TrustedGroup:admin - this matches if you are a member of TrustedGroup.

If it matches, you get the rights (a) and - now the difference because of the modifier - ACL processing CONTINUES! So if there is another match for that group or your user or Known: or All: you will get those rights, too.

If it does not match, ACL processing continues - with the item ACLs (if there are any) or with default ACLs (if there are no item ACLs) and finally with the "after" ACLs.

While they represent the same thing, inheriting from the defaults has the advantage of automatically following any further change introduced in the defaults.

Hierarchical ACL processing

If you have enabled hierarchic (see above), then the items are understood as a hierarchy and permissions set on higher-level items may influence the user's permissions on lower-level items.

In a nutshell, if the current item has no acls at all (i.e., not even the empty ''), then the parent item's ACLs are checked, and then its parent's, and so on until there are no parent items or an ACL is found.

All normal ACL rules are followed, as described above, but if there are no ACLs on the current item, its ancestors are successively traversed (from child to parent) until an ACL is found. Consider the following examples for an item named A/B/C/D, that contrasts how processing occurs with and without the feature enabled (assuming there's no ACLs on D, C and B):

Note that before, default, and after are not applied once per item in the hierarchy, but rather once overall during the processing of item A/B/C/D. As for the default rights, they still work as before, but instead of being included when the current item contains no ACL, it is only used if none of the items in the hierarchy contain any ACL.

Groups

User groups make it easier to specify rights for bigger groups. Normally, the name of the group page has to end with Group like FriendsGroup. This lets MoinMoin recognize it as a list of usernames. This default pattern could be changed (e.g. for non-english languages etc.), see HelpOnConfiguration.

Only SomeUser's friends can read and edit this page:

acl: SomeUser:read,write SomeUser/FriendsGroup:read,write

SomeUser/FriendsGroup would be a page with each top-level list item representing a wiki username in that group:

acl: SomeUser:read,write,admin
 * JoeSmith
 * JoeDoe
 * JoeMiller

A page named AdminGroup could define a group of that name and could be also protected by ACLs:

acl: AdminGroup:admin,read,write All:read
 * SomeUser
 * OtherUser
   * This is currently ignored.
Any other text not in first level list will be ignored.

A first level list is one with only one space before the asterisk (and there also has to be one space after the asterisk). The following won't work:

  * some user
-- two spaces like so and it doesn't work

You can configure which page names are considered as group definition pages (e.g. for non-english wikis):

page_group_regex = ur'(?P<all>(?P<key>\S+)Group)'    # this is the default

Please note that after creating some group page(s), you maybe want to use those groups in some ACLs in your wiki configuration or on your pages (or nothing will happen - moin does not use something like pre-defined groups).

Usage cases

Public community Wiki on the Internet

The most important point here is to use ACLs only in cases where really needed. Wikis depend on openness of information and free editing. They use soft security to clean up bad stuff. So there is no general need for ACLs. If you use them too much, you might destroy the way wiki works.

This is why either ACLs should not be used at all (default) or, if used, the wikiconfig.py should look similar to that:

before = u'WikiEditorName:read,write,admin,create +AdminGroup:admin BadGuy:'

The default default option should be ok for you:

default = u'Known:read,write,create All:read,write,create'

A good advice is to have only a few and very trusted admins in AdminGroup (they should be very aware of how a wiki works or they would maybe accidently destroy the way the wiki works: by its openness, not by being closed and locked!).

If using AdminGroup, you should make a page called AdminGroup and use it to define some people who get admin rights.

Specifing BadGuy like shown above basically locks him out - he can't read or edit anything with that account. That makes only sense if done temporarily, otherwise you also could just delete that account. Of course, this BadGuy can also work anonymously, so this is no real protection (this is where soft security will apply).

Wiki as a simple CMS

If you want to use a wiki to easily create web content, but if you don't want edits by the public (but only by some webmasters), you maybe want to use that in your wikiconfig.py:

default = u'All:read'
before  = u'WebMaster,OtherWebMaster:read,write,admin,create'

So everyone can read, but only the Webmasters can do anything else. As long as they are still working on a new page, they can put

acl: All:

on it, so nobody else will be able to see the unfinished page. When finished, don't forget to remove that line, so that default will be used.

Some page(s) could also allow public comments (like one being called PublicComments), so you give more rights on that page:

acl: All:read,write

Wiki on Intranet

If you want to use a wiki on your intranet and you trust your users (will not do hostile stuff like locking others out or hijacking pages) to use the admin functionality in a sensible way, you maybe want to use:

default = u'Known:admin,read,write,create All:read,write,create'
before  = u'WikiAdmin,BigBoss:read,write,admin,create'

So everyone can read, write and change ACL rights, WikiAdmin and BigBoss are enforced to be able to do anything, known users get admin rights by default (so they get it as long as no other ACL is in force for a page).

Consequences:

• on a new item, the item creator can put any ACLs he wants
• on existing items, not having ACLs yet, any known user can set up any ACLs he wants

• all people (except WikiAdmin and BigBoss) can be locked out by anybody ("known") else on items without ACLs

Wiki as a public company website

If you want to use a wiki as the company website, and don't want every user being able to change the company website content, you may want to use something like this:

default = u"TrustedGroup:admin,read,write,create All:read"
before = u"AdminGroup:admin,read,write,create +TrustedGroup:admin"

This means that:

• by default known and anonymous users are only allowed to read items

• on a new item, users in TrustedGroup can put any ACLs they want

• on existing items, not having ACLs yet, any user in TrustedGroup user can set up any ACLs he wants

• all people, except people in AdminGroup, can be locked out by other admins or trusted users

• people in TrustedGroup get to use their admin rights on any item they're able to write, even if there are specific ACLs

Comments on read-only page

You can easily add a comments section to a read-only page by using a writable subpage, and allowing users to write on it. For example, you can define SomePage like this:

acl: SomeUser:read,write All:read
'''Some read-only content'''

...

''' User comments '''
[[Include(SomePage/Comments)]]

And SomePage/Comments like this:

acl: All:read,write
Add your comments about SomePage here.