DokuWiki

It's better when it's simple

User Tools

Site Tools


acl

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Both sides next revision
acl [2020-11-22 03:02]
Fred23 [User Wildcards]
acl [2020-11-22 07:07] (current)
Aleksandr old revision restored (2019-10-31 10:06)
Line 1: Line 1:
 +====== Access Control Lists (ACL)s ======
  
 +[[DokuWiki]] --- like most wikis --- is very open by default. Everyone is allowed to create, edit and delete pages. However ​sometimes it makes sense to restrict access to certain or all pages. This is when the //Access Control List// (ACL) comes into play. This page gives an overview of how ACLs work in DokuWiki and how they are configured.
  
 +{{:aclexample.png?400|}}
  
 +===== Configuration and Setup ===== 
  
 +ACLs can be enabled in the [[installer]] and an initial ACL policy is set there as well. To manually enable ACLs, switch on the [[config:useacl]] option and create a copy of the example files '​'​conf/​acl.auth.php.dist'​'​ and '​'​conf/​users.auth.php.dist'​'.​ Rename the files to '​'​conf/​acl.auth.php'​'​ and '​'​conf/​users.auth.php'​'​ respectively.
 +
 +==== See also =====
 +
 +There are a few more config options and features that relate to authentication, user registration and ACL setup. Please check their respective wiki pages to get more information:
 +
 +  * Config option [[config:useacl]] -- enable ACL usage
 +  * Config option [[config:superuser]] -- setup superusers with ACL granting rights 
 +  * Config option [[config:defaultgroup]] -- the default group to which new users are added
 +  * [[plugin:usermanager|User Manager]] -- managing users
 +  * [[auth|Authentication Backends]] -- identify users from different data sources
 +  * [[faq:regdisable|FAQ: How to disable open user registration]] -- replaces $conf[openregister]
 +
 +:!: **WARNING:** DokuWiki's ACL feature has 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.
 +
 +===== Access Restrictions =====
 +
 +Access restrictions can be bound to [[pagename|pages]] and [[namespaces]]. There are seven permissions: //none//, //read//, //edit//, //create//, //upload//, //delete// and //admin//. Each higher permission contains the lower ones, with read being the lowest and delete the highest one. You should note that create, upload and delete permissions can only be assigned to namespaces.
 +
 +Rules that were set to namespaces apply on media namespaces as well as for page namespaces.
 +
 +When DokuWiki checks which rights it should give to a user, it uses all rules matching the user's name or the groups he or she is in. The rule that provides a user's permission is chosen according to the following process:
 +
 +  * 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.
 +
 +Users are in the groups they were assigned to in the user manager (or the auth backend). However there are two **groups** that are somewhat special:
 +
 +  * **@ALL** Everyone, even users not logged in, is a member of the ALL group. You can use this group to restrict access for all users (as a default setting) and then relax the permissions for some selected users. 
 +  * **@user** All self-registered users are by default automatically a member of the group 'user'. Use this to give permissions to 'logged-in' users. The name of this group is configured through the [[config:defaultgroup]] option. 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.
 +
 +==== Editing ACLs ====
 +
 +To easily add new or change existing access rules, you should use the [[plugin:acl|ACL Manager]] which is available from the Administration menu. A detailed description of its interface can be found [[plugin:acl|here]].
 +
 +Basically there are three steps to add a new ACL rule:
 +
 +  - select the namespace or page to restrict from the upper left tree navigation
 +  - choose to whom the ACL rule should apply
 +    * by selecting a known group or user from the dropdown menu
 +    * or by selecting "User:" or "Group:" and entering the group or user name in the field
 +  - set the appropriate permissions
 +
 +Existing rules can be modified or deleted in the table at the bottom of the ACL manager.
 +
 +==== ACLs by Example ====
 +
 +In this section we will explain how access rules work, using a fictional example setup that looks like this in the ACL manager:
 +
 +{{:aclexample.png}}
 +
 +Let's have a look at each line:
 +
 +  - This sets permission for everyone in the main namespace, allowing everybody to edit and create pages. However upload is not allowed.
 +  - User //bigboss// is given full rights.
 +  - Now the access for the ''devel'' namespace is restricted. Nobody is allowed to do anything.
 +  - Well not nobody really---we give members of the //devel// group full rights here.
 +  - And of course //bigboss// is allowed, too, and they're the only one who can delete uploaded files.
 +  - And the //marketing// group may read everything in the ''devel'' namespace, but read only.
 +  - However the devel team doesn't want their boss to see the ''funstuff'' page---remember exact pagematches override namespace permissions.
 +  - And finally the //marketing// group is allowed to edit the ''devel:marketing'' page as well.
 +  - Then the permissions for the namespace ''marketing'' are set. All members of the //marketing// group are allowed to upload there---other users will be matched by line 1 so they can still create and edit. //bigboss// inherits their rights from line 2 so they can still upload and delete files.
 +  - The last line finally restricts the start page to readonly for everyone. Only superusers will be able to ever edit that page.
 +
 +Let's have a look at a second example to better understand **specific matching**:
 +
 +{{:aclexample2.png}}
 +
 +FIXME - Should the group be changed to @user in the table, which I thought was the default group?
 +
 +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 ''None''
 +  - bob, a regular user
 +    * four rules match, #1, #2, #4, #6
 +    * rule #6 wins as its an exact match
 +    * bob's permission level is ''Delete''
 +  - 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 ''None''
 +  - 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 ''Delete''
 +
 +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 =====
 +
 +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 only overwrite existing media files if the [[config:mediarevisions|media revisions]] option is enabled.
  
 ==== User Wildcards ==== ==== User Wildcards ====
acl.txt · Last modified: 2020-11-22 07:07 by Aleksandr