TechDocs/Wiki/ACLTutorial

Contents

  1. How to use ACLs
    1. Best practices
      1. Read the documentation
      2. Have a plan B
      3. Make collaboration easy
    2. Exemplary use-cases
      1. How to hide a page from public
      2. How to use ACL groups
        1. Step 1: Create an ACL group
        2. Step 2: Restrict access to your page
      3. Allowing anonymous editing
    3. Common pitfalls
      1. Don't add additional whitespace
      2. Remember the 'Group' in group names

How to use ACLs

Access control lists (ACLs) allow you to override the default permissions on a wiki page and all its sub-pages. This page shows some hands-on advice on their usage.

Best practices

Read the documentation

In case the use-cases covered by this how-to don't cover your needs, here are a few handy resources:

Have a plan B

If you are not careful, you can easily "lock yourself out" of a page. Therefore, give WikiCaretakers admin rights while working on the ACL. Once you are confident everything is correct, you can remove the entry.

You can do this by starting your ACL line like this: 

#acl +Group/WikiCareTakers:read,write,admin

As you expand the ACL line, add further restrictions after the WikiCaretakers entry. Because ACLs are parsed from left to right, the first matching entry "wins".

If you are working together with another member of your team, you can of course add their user name instead of the wiki caretakers group.

Make collaboration easy

Remember: the more you restrict access to your page, the less people can improve it!

Ask yourself:

Remember: The beauty of a wiki is that anybody can just fix errors they encounter. Nobody likes the bureaucracy of having to request permission to collaborate on the wiki!

Exemplary use-cases

How to hide a page from public

You can remove the read permission from non-authenticated users as follows: 

#acl Known:read,write,revert,delete,admin All:

Explanation:

  1. Known users (i.e. all users that are logged in) have full access rights

  2. For All users not handled by the first rule (i.e. all anonymous visitors), any permissions are removed.

How to use ACL groups

ACL groups are a good way to make an alias for several users, so that you don't need to mention each of them on every page.

Let's take a look at them using this example:

  • You are part of a local group (e.g. LocalGroups/Freedonia)
  • For a new campaign, you want to collaborate using a wiki page
  • However, you don't want anyone else to see the campaign page until it is done

Step 1: Create an ACL group

First of all, you need an ACL group page. The group page contains a bullet list of user (and group) names. There can be some additional markup, but you should keep it simple.

  • Let's call it Group/FreedoniaMembers. An explanation is given in the comments (lines starting with "##"): 

## The "#acl" line gives the members of the group full access rights, ''read'' rights to every logged in user, and hides the page from public internet.
#acl Group/FreedoniaMembers:read,write,delete,revert,admin Known:read All:

##  If you want, you can add a short description with a link to your group's main page:
Members of [[LocalGroups/Freedonia]]:

## User names are listed as a regular bullet list.
## If you want to add additional text, you can do so in a separate line (as shown with username2).
## You can also add group names.
 * username1
 * username2
 [[Fellows/username2]]
 * username3
 * Group/OtherGroup

Step 2: Restrict access to your page

Let's say you now want to restrict access to LocalGroups/Freedonia/Internal. Decide which of the examples below best suits your needs and start from there.

Variant "No access except us": 

#acl Group/FreedoniaMembers:read,write,delete,revert,admin All:

Variant "Others may read, but not the rest of the world": 

#acl Group/FreedoniaMembers:read,write,delete,revert,admin Known:read All:

Allowing anonymous editing

Sometimes you want to lower the access barrier so that casual contributors can edit a page, even if they don't have an FSFE account.

Obviously, this also allows vandalism. It is therefore a good idea to keep a close eye on such a page, and to make it read-only when anonymous access is no longer required.

The ACL may look like this: 

#acl yourUserName:read,write,delete,revert,admin Known:read,write,revert All:read,write

Explanation:

  1. yourUserName has full access rights
  2. Users who are logged in can normally view and edit the page, as well as reverting changes (in case of vandalism)
  3. Anyone can view and edit the page, even if not logged in.

Common pitfalls

The following is a list of common problems that people have when using ACLs.

Don't add additional whitespace

Spot the difference: 

#acl Known:read,write,admin,revert,delete All:
## → OK

#acl Known: read,write,admin,revert,delete All:
## → PROBLEM: nobody has access rights

There must not be any space between the colon (':') and the access modifiers.

Remember the 'Group' in group names

These two are not the same: 

#acl Group/LinzMembers:read,write,admin,delete Known:read,write
## → OK

#acl LinzMembers:read,write,admin,delete Known:read,write
## → PROBLEM: user "LinzMembers" gets rights, not group "Group/LinzMembers"

Category/Help Category/HowTo

TechDocs/Wiki/ACLTutorial (last edited 2017-03-16 18:38:37 by jzarl)