Access Control Lists

Access Control Lists (ACL's) allow you to control the permissions of a user or a group of users (which you define, see HelpOnGroups). You can define permissions for the entire wiki, or for select pages of the wiki.

Using ACL's, you can easily configure the wiki so that anonymous users can only read, but not edit pages. You can create pages that the general audience can't read until you're read to publish. You can set permissions so that only certain users are able to edit.

To use ACLs, you need either access to the wikiconfig.py (for setting global ACLs), or the admin right on the specific page where you want to set (or change) ACLs.

1. Understanding Permissions & Groups

1.1. Basic Permissions

Available rights you can use in an ACL entry:

• read - users will be able to read a page, and download its attachments.

• write - users will be able to edit (write) a page, and upload attachments.

• delete - users will be able to delete a page and it's attachments.

• revert - users will be able to 'revert' a page back to an older revision.

• admin - users will be able to change the "#acl" line on a page, as well as grant and/or revoke "admin" privileges from others.

There is no separate rename right. Renaming a page requires that a given user has the read, write and delete rights.

Anonymous users (i.e not logged in) are not able to delete or rename pages (even if specifically granted to the All group).

Attachments are protected by the ACLs of the page they are attached to.

You need to already have admin rights to be able to add or modify an ACL line to a page. If you are the wiki administrator, you will want to make sure you grant yourself admin rights for the entire wiki (see site-wide configuration below).

Allowable permissions can be limited with the acl_rights_valid setting in your wikiconfig.py file. For example, include all permissions but delete to prevent any page from ever being deleted. (see site-wide configuration below).

1.2. Basic Groups

Permissions can be assigned to individuals, groups (which you define), or special groups (system groups that have special meaning). They are:

• User - where User matches a specific username and triggers only if it matches exactly (including case-sensitivity).

• SomeGroup - where SomeGroup matches a specific group name, which you define (see HelpOnGroups).

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

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

• All - a special group that means "everyone" (both logged in (i.e. Known) and anonymous users).

2. Syntax & Usage

Using ACLs in moin is as easy as including a control line on the page you want to control. The ACL command should be the top-most line on your wiki page, and syntax is as follows:

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

Where User, SomeGroup, and right (the permission as read, write, delete, revert, admin) are defined in the section above.

Default is a special entry which inserts at the given place the entries from acl_rights_default. This is covered in more detail in the #Default section below.

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

A simple example would be:

#acl JohnDoe:read,write,delete,revert,admin EditorGroup:read,write,revert All:read

In this example, this will allow JohnDoe to read and write, as well as perform any other action on that page, while anyone part of the EditorGroup will be able to read, write, and revert this page. All other users can only read it. (Keep in mind that the configuration settings in your wikiconfig.py can override some page-specific ACLs). Also see "Usage Examples" below.

3. Site-wide Configuration

These configuration items are used to set up ACLs on the entire wiki site, and are set in your wikiconfig.py file (see also HelpOnConfiguration).

4. Access control lists

ACLs control who may do what, see HelpOnAccessControlLists.

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 site-wide page admins or page editors.

• default means what is done if no ACLs are specified on the page. It is equivalent to writing exactly these ACLs onto a page. These are also the rights that are merged if Default is written among the ACLs in the page.

• 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 page-based ACLs.

The u"" notation used for the configuration strings means unicode and must be there.

5. ACL processing

This section applies to single wiki pages containing ACLs but may also apply to the whole wiki if the ACL is included in the wiki config (see HelpOnConfiguration).

5.1. Order of processing ACL entries

When a user is trying to access an ACL-protected resource, the ACL entries will be processed in the order they are found. The first ACL entry matching the user will determine whether the user has access to that resource or not and processing will stop. Due to this first match algorithm, you should arrange your ACL entries in the following order: 1) single usernames, 2) special groups, 3) more general groups, 4) Known and finally 5) All.

For example, the following ACL means that SomeUser will be given the right to read and write the resources protected by that ACL, while any other user who is a member of SomeGroup may also be given admin rights and every other user is only able to read the resource.

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

5.2. ACL prefix modifiers

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

For 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 special only for SomeUser, because when the admin permission is queried for SomeUser, it will be denied and processing will stop. In all other cases (different user or different permission requested), processing will continue.

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

+All:read means that when any user is requesting read permission, it will be given and processing will stop. In all other cases, processing will continue. If the admin permission is queried for SomeUser, it will be denied and processing will stop. In all other cases (different user or different permission requested), processing will continue. Finally, if a member of SomeGroup is requesting a permission; it will be given if specified there, and denied if not. All other users have no other permission (unless they are given site-wide in the wiki config).

Note that you probably do not want to use the second and third examples in page ACLs whereas they can be very useful for wiki configuration ACLs.

6. Inheriting from 'Default'

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:

acl_rights_default = u"TrustedGroup:read,write,delete,revert All:read" acl_rights_before = u"AdminGroup:admin,read,write,delete,revert +TrustedGroup:admin"

Now, you have some page 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 acl_rights_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,delete,revert All:read

Lets look at the first example in this section:

acl_rights_before = u"AdminGroup:admin,read,write,delete,revert +TrustedGroup:admin"

ACLs are processed in the order of "before" then "page/default" then "after", and from 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 page ACLs (if there are any) or with default ACLs (if there are no pages 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.

7. Hierarchical ACL processing

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

If the current page doesn't contain an #acl statement, then the parent page's ACL is used instead (or its parent, and so on until there are no parent pages).

Consider the following examples for a page named A/B/C/D, that contrasts the how processing occurs with and without the feature enabled:

As for the default rights, they still work as before, but instead of being included when the current page contains no ACL, it is only used if none of the pages in the hierarchy contain any ACL.

Please note-- ACL_hierarchic behavior in moinmoin versions prior to 1.8.4 behaved differently: the parent page's ACL are not appended anymore to the sub-page's ACL. All ACLs for a sub-page have to be explicitly listed in that page now.

8. Usage Examples

8.1. 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:

acl_rights_before = u'WikiEditorName:read,write,admin,delete,revert +AdminGroup:admin BadGuy:'

The default acl_rights_default option should be ok for you:

acl_rights_default = u'Known:read,write,delete,revert All:read,write'

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).

8.2. 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:

acl_rights_default = u'All:read' acl_rights_before = u'WebMaster,OtherWebMaster:read,write,admin,delete,revert'

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 acl_rights_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

8.3. 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:

acl_rights_default = u'Known:admin,read,write,delete,revert All:read,write' acl_rights_before = u'WikiAdmin,BigBoss:read,write,admin,delete,revert'

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 acl_rights_default (so they get it as long as no other ACL is in force for a page).

Consequences:

• on a new page, the page creator can put any ACLs he wants
• on existing pages, 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 pages without ACLs

8.4. Wiki as a public company page

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

acl_rights_default = u"TrustedGroup:admin,read,write,delete,revert All:read" acl_rights_before = u"AdminGroup:admin,read,write,delete,revert +TrustedGroup:admin"

This means that:

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

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

• on existing pages, 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 page they're able to write, even if there are specific ACLs

8.5. 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.

9. See Also

• HelpOnAutoAdmin: The AutoAdmin feature allows users to be granted admin rights over a subset of the wiki