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

:!: **警告:** Dokuwiki 的 ACL 特性已经存在了相当一段时间，应该是非常稳定的。然而，如果你担心未授权用户能访问维基内容这一风险，就绝不要把它放到可通过网络访问的计算机上。

===== 配置 ===== 
ACL 可以在[[:installer|安装向导]]里被激活，同时会初始化一个 ACL 策略。如果要手动激活 ACL，打开 [[config:useacl]] 选项并把 ''conf/acl.auth.php.dist''、''conf/users.auth.php.dist'' 这两个文件重命名为 ''conf/acl.auth.php''、''conf/users.auth.php''。

==== 参见 ====

还有一些额外的选项和特性与授权、用户注册以及 ACL 设置有关。请参考它们相应的维基页面来获取更多信息：

  * 配置选项 [[config:useacl]] -- 激活 ACL
  * 配置选项 [[config:superuser]] -- 设置拥有 ACL 授予权限的超级用户
  * 配置选项 [[config:disableactions]] -- 允许你禁用开放注册
  * 配置选项 [[config:defaultgroup]] -- 新用户的默认组
  * [[plugin:usermanager|用户管理器]] -- 管理用户
  * [[:auth|认证后端]] -- 使用不同数据源来验证用户
  * [[faq:regdisable|FAQ: 如何禁用开放的用户注册]]
===== 访问限制 =====

访问控制可以针对[[pagename|页面]]或者[[namespaces|命名空间]]。共有7种权限：//无//、//读取//、//编辑//、//创建//、//上传//、//删除//以及//管理//。高权限会包含低权限，其中读取是最低的权限，删除是最高的权限。需要注意的是，创建、上传和删除权限只能应用于命名空间。

为命名空间设置的规则也会应用到其下的媒体文件和页面((Rules that were set to namespaces apply on media namespaces as well as for page namespaces.))。

当 Dokuwiki 检查它应该给用户何种权限时，它会使用所有匹配该用户及其所在组的规则。最终应用的权限规则由以下方式选出：

  * 规则的应用范围越接近指定的页面，优先级就越高 —— 我们称之为“specific matching”。((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.))

在用户管理(或者验证后端)中，用户总是属于某个组。然而，有两个组 **groups** 有点特别:

  * **@ALL**。每个人，即便是没有登录的人，都属于这个组。你可以使用这个组来限制所有人的访问权限(作为默认设置)，然后再对特定用户放宽权限。 
  * **@user**。所有自主注册的用户，默认都属于这个组。用这个组来给予“已登入”用户权限。这个组的名字可以通过[[config:defaultgroup|默认组]]选项配置。与虚拟的“ALL”组不同，“user”组是真实的组，是在使用简单身份验证后端时所有用户默认加入的组。如果你使用不同的验证后端，你需要使用这个后端所提供的组。

在内部以及 ACL 管理器中，组由“@”前缀和组名来表示。
==== 编辑 ACL ====

想方便地添加新规则或更改已存在的规则，你需要使用“管理”菜单中的[[plugin:acl| ACL 管理器]]。关于它的更多描述可以在[[plugin:acl|这里]]找到。

基本上，增加一条新的 ACL 规则有三个步骤： 

  - 从左上角的树状导航栏中选择需要限制的命名空间或者页面
  - 选择需要应用 ACL 规则的组或人
    * 从下拉框中选择已知组或用户
    * 或者，选择“User:”或“Group:”，然后输入组名或用户名
  - 设置适当的权限

已有规则可以在 ACL 管理器下面的表格中修改或者删除。
==== ACLs示例 ====

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

{{:aclexample.png}}

我们一行一行地看：

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

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

{{:aclexample2.png}}

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

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


===== Background Info =====

这段是背景知识，告诉你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 [[config:superuser]] option.

^ Name   ^ Level ^ applies to        ^ Permission                               ^ DokuWiki constant ^
| none   |  0    | pages, namespaces | no permission -- complete lock out       | AUTH_NONE         |
| read   |  1    | pages, namespaces | read permission                          | AUTH_READ         |
| edit   |  2    | pages, namespaces | existing pages may be edited             | AUTH_EDIT         |
| create |  4    | namespaces        | new pages can be created                 | AUTH_CREATE       |
| upload |  8    | namespaces        | mediafiles may be uploaded               | AUTH_UPLOAD       |
| delete |  16   | namespaces        | mediafiles may be overwritten or deleted | AUTH_DELETE       |
| admin  |  255  | admin plugins     | superuser((see [[config:superuser]])) can change admin settings      | AUTH_ADMIN        |

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

<file>
*                     @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
</file>

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.
==== User Wildcards ====

这段是说如果你的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. 

<file>
#
# 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
</file>

:!: **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 [[http://bugs.dokuwiki.org/index.php?do=details&task_id=1955|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.