Access Control Lists (ACL)

DokuWiki – 正如其他wiki — 默认是很开放的. 每个人都能创建、编辑、删除页面. 但是有时候对一些甚至所有的页面作个限制也是合理的。 这时候我们就要用到 Access Control Lists (ACL) 了。 本页面将介绍怎么使用ACL和怎么配置它。

WARNING: DokuWiki's ACL feature has now been included for some time and should be pretty stable. However, if you are concerned about the risk of unauthorized users accessing information in your wiki, you should never put it on a computer accessible from the Internet…

ACL 需要在 installer 里被enable，同时会初始化一个ACL策略给你. 如果要手工搞一个ACL的话, 打开这个 useacl 选项并把这两个文件 conf/acl.auth.php.dist 、 conf/users.auth.php.dist 改名成 conf/acl.auth.php 、 conf/users.auth.php .

若想设置更精细的权限，比如“授权”“注册”“访问控制表(ACL)”，请参考下面这些页面: （短句比较难翻译，英文留在后面）

• Config option useacl – 使ACL生效
• Config option superuser – 设置管理员，让他能设置ACL setup superusers with ACL granting rights)
• Config option disableactions – 关闭开放的注册 allows you to disable open registration
• Config option defaultgroup – 新用户默认进哪个组 the default group to which new users are added
• User Manager – 管理用户 managing users
• Authentication Backends – 使用其他后端软件管理用户的注册信息（比如说mysql，甚至与php论坛集成） identify users from different data sources
• FAQ: 如何禁止用户注册 How to disable open user registration

访问限制可以有两个范围，页面级和命名空间级 pages and namespaces. 有7种权限: none, read, edit, create, upload, delete and admin. 只要赋予了高级权限，就自动包括低级权限了。如果你一口气写了好几个权限，最终生效的将是最低的那个。 注意 create, upload and delete 权限只能在namespaces这个范围使用。

Rules that were set to namespaces apply on media namespaces as well as for page namespaces. 这句看不懂，大概是说，如果你针对namespace设置权限，那么图片等媒体的权限跟页面权限是一起生效的。

当DokuWiki校验是否应该给一个用户某项权力时，它会综合考虑这个用户拥有的权限和此用户所属的组的权限。如果发生矛盾，处理过程是这样的：

• 这句不好翻，大意是，如果你允许某个用户编辑某个页面，但是不允许他编辑这个页面所属的namespace，那么他还是能编辑这个页面的。 Rules which match closer to the namespace:page are preferred over rules which match further away – we call this “specific matching”.
• 这句不太肯定，我猜是，如果你不允许某个组编辑某个页面，但是你允许这个组中的某个人编辑这个页面，那他还是能编辑的。 When more than one rule matches at the same level, the rule giving the highest access level is preferred.

在用户管理（或者auth backend）中，用户总是属于某个组。然而，有两个组 groups 有点特别:

• @ALL. 每个人，即便是没有登录的人，都属于这个组。你可以先限制这个ALL组访问某个资源，然后再授权给某些用户。
• @user. 所有自主注册的用户，默认都属于这个组。我们可以把它认为是所有的“登录用户”。你也可以在defaultgroup修改这个组的名字。这个组跟ALL那个组是不太一样的。后面我就不懂了。 Unlike the virtual “ALL” group, the “user” group is a real group to which all users are added automatically when using the plain auth backend. If you use a different backend you need to use the groups provided by this backend.

Groups are represented internally and in the ACL manager by a prepended @ character to the group name.

想方便地编辑访问规则，装个ACL Manager更给力。当你用admin登录后，就能在“管理”菜单里用它了。想对这个插件了解更多，点这里here 。 基本上，增加一条新的ACL规则有三个步骤：

1. 从左上角的树状导航栏中选择一个 namespace 或者 page
2. 选择一个组或者一个人
   • 直接在下拉框里选择也行
   • 选择 “User:” or “Group:” 然后手工输入名字也行
3. 设置你要设置的权限

在ACL manager 中还可以编辑你从前设置好的访问规则。

在这个部分，我们举例说明访问规则是怎么工作的：

我们一行一行地看：

1. 任何人都能创建并编辑页面，但是不能upload.
2. 用户 bigboss 拥有所有权限。
3. 此刻，devel这个namespace谁都不能动。
4. 哦，看到这一行，我们发现事实不是这样，devel组（有个@标志的是组，没有的是人）是拥有完全权限的。
5. 当然 bigboss 也被授权了 – 而且他是唯一一个有权删除upload文件的人.
6. 然后，@marketing组能读devel这个namespace的所有内容，但是只能读。
7. 然而，devel组里的兄弟们不想让 bigboss 读devel namespace中的 funstuff页面。这就是上面说的那个“specific matching”原则。
8. 最后， marketing 组可以编辑devel:marketing页。
9. namespace marketing 也设置了. marketing 组的成员都被允许upload - 其他用户因为规则1的授权，能够创建、编辑，但是不能upload. bigboss 则因为规则2 的授权，他能upload 并 delete 文件.
10. 最后一行限制了主页（start 页面），任何人都只能读，不能改。（只有超级用户才能改）。

下面这个例子可以让你更好地理解 specific matching: （俺就不翻译了）

This time we look what rules will match for different users when trying to access the page private:bobspage.

1. abby, a regular user
   • three rules match, #1, #2, #4
   • rule #4 is closest, it matches at the namespace level so it takes precedence over the other three
   • abby's permissions level is 0
2. bob, a regular user
   • four rules match, #1, #2, #4, #6
   • rule #6 wins as its an exact match
   • bob's permission level is 16
3. bob forgets to login and tries to access his page
   • two rules match, #1 & #4
   • rule #4 is closer, it wins
   • bob's permission level while not logged in is 0
4. charlie, a staff member
   • five rules match, #1 - #5
   • two rules match at namespace level, #5 gives charlie the higher permission so it wins
   • charlie's permission level is 16

Note rule #5, which appears to duplicate rule #3. Without it, staff members wouldn't be able to access the private namespace as rule #4 would keep them out.

这段是背景知识，告诉你ACL文件存在哪里，但是不建议你直接修改，所以俺不翻译了。 Access restrictions are saved in a file called conf/acl.auth.php, which should be writable by the webserver if you want to use the ACL admin interface described above. It is not recommended to edit this file manually. Use the admin interface instead.

Empty lines and shell-style comments are ignored. Each line contains 3 whitespace separated fields:

• The resource to restrict. This can either be a pagename or a namespace. Namespaces are marked by an additional asterisk (see examples below).
• A group or user name. Groupnames are marked by a leading @ character.
• A permission level (see below).

There are 7 permission levels represented by an integer. Higher levels include lower ones. If you can edit you can read, too. However the admin permission of 255 can not be used in the conf/acl.auth.php file. It is only used internally by matching against the superuser option.

Here is an example setup matching the first example given above:

*                     @ALL        4
*                     bigboss    16
devel:*               @ALL        0
devel:*               @devel      8
devel:*               bigboss    16
devel:*               @marketing  1
devel:funstuff        bigboss     0
devel:marketing       @marketing  2
marketing:*           @marketing  8
start                 @ALL        1

Please note, that order does not matter in the file. The file is parsed as whole, then a perfect match for the current page/user combo is searched for. When a match is found further matching is aborted. If no match is found, group permissions for the current page are checked. If no match is found the check continues in the next higher namespace.

Note: To configure users or groups with special chars (like whitespaces) you need to URL escape them. This only applies to specialchars in the lower 128 byte range. The ACL file uses UTF-8 encoding so any multibytechars can be written as is.

Note: When using $conf['authtype'] = 'ad'; and groups names with spaces needing to be written in the acl.auth.php with a ”%5f” replacing the spaces instead of ”%20”. This is because Group names with spaces are first converted into underscores “_” which are ”%5f”.

Note: The delete permission affects media files only. Pages can be deleted (and restored) by everyone with at least edit permission. Someone who has upload permissions but no delete permissions can not overwrite existing media files anymore.

这段是说如果你的wiki有非常多的注册用户的话，你可以用通配符。 这段也不翻译了。

It is possible to use user wildcards in the ACLs. This can be useful for Wikis with many registered users, if you want to give each user a personal namespace where only he/she has write access, and you don't want to edit the ACLs for each user. To accomplish that %USER% is replaced by the username of the currently logged in user.
In the following example a logged in user gains full access (upload/delete) permissions for the user's namespace users:<username>:* and revoke all access from other namespaces located in users:*
In this case logged in user has access to own namespace only and have not access to users namespaces (even view names of namespaces) of other users.

#
# Grant full access to logged in user's namespace
users:%USER%:*          %USER%  AUTH_DELETE
#
# Allow to browse own namespace via INDEX
users:                  %USER%  AUTH_READ
#
# Allow read only access to start page located in <users> namespace 
users:start             %USER%  AUTH_READ
#
# Disable all access to user's home namespaces not owned by logged in user (include view namespaces via INDEX) 
users:*                 @user   AUTH_NONE

Note: current version 2009-12-25c “Lemming” has some caveat. If you add, update or remove ACL from GUI admin interface then DokuWiKi engine will replace %USER% in the second field of ACL to %25USER%25 that is a bug FS#1955. To avoid it, - change permissions manually only (file: conf/acl.auth.php) or correct them manually after each operations with ACL from GUI because mask %25USER%25 does not work as expected, only %USER% should be used in the conf/acl.auth.php.

Note: The wildcard was recently changed from @ to % – if you are upgrading from an older version you need to adjust your ACL setup accordingly.