Differences

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

--- wiki:acl [2007/08/24 08:50] – jas
+++ wiki:acl [2007/08/24 09:51] (current) – jas
@@ Line 1: / Line 1: @@
 ====== Access Control ======
-In order to understand how to control access to your Wiki site, you need to understand DokuWiki authentication.  Authentication determines who can access your site, and access control determines what they can access.
+Access Control is broken down into Authentication, and Authorization.  Authentication determines who can access your Wiki site, and Access Control determines what they can access on your site.
 ===== Authentication =====
-DokuWiki has been setup by default to allow everyone with a CSE account to login to your site.  You can add your own custom non-CSE accounts through the User Manager in the Admin menu.  You can also enable registration on your Wiki in order to allow outside users to register for an account on your Wiki.  This process is completely automated in that the user will be sent a registration message, and will need to access a particular URL to activate their account.  **Due to spam activity, this mode of operation is highly discouraged.**
+By default, all local Wikis have been setup to allow everyone with a CSE account to login.  Similarly, by default, all content is viewable by anyone in the world.  If you are a site admin, you can add your own custom non-CSE accounts through the User Manager in the Admin menu.  This means that if you are collaborating on a project with someone who does not have a CSE account, you can create a Wiki account for them.  You can also enable registration on your Wiki in order to allow outside users to register for an account on your Wiki.  The registration process is completely automated in that the user will be sent a registration validation message, and will need to access a particular URL in order to activate their Wiki account.  **Spammers abuse these types of systems.  Due to spam activity, this mode of operation is highly discouraged.**
-===== Groups =====
+===== Authorization =====
+Authorization can be broken down into two areas -- groups and access control lists (ACLs).
+==== Groups ====
 DokuWiki users can be placed into groups.  The following groups come preconfigured with our DokuWiki installation:
@@ Line 19: / Line 23: @@
 You can manually add users to groups through the User Manager in the Admin menu.  You cannot remove users from the cse, wiki, or ALL groups.
-Each group is represented by a Wiki page in the ":group" namespace.  That is, if you add a user //X// to the group //mygroup//, then :group:mygroup will contain "X".  This means that if you need to add many users to a group, you may find it easier to edit the group file directly using the Wiki interface!  To edit an existing group, you can visit the group namespace through the Wiki "Index", and then simply choose the "Edit page" button.  If you wish to create a new group that has not already been created through the User Manager, you must visit the URL directly like this:
+Each group is represented by a Wiki page in the ":group" namespace. A group page contains a list of users, one user per line.  That is, user //X// is in group //mygroup//, then :group:mygroup will contain "X".
+There are two ways to add a user to a group.  You can add users to groups using the "User Manager" which is available by clicking on the "Admin" button.  Alternatively, if you need to bulk add users, you can simply access the groups Wiki page through the Wiki interface, and edit the file directly, even cutting and pasting from other sources.   cse, wiki, and ALL groups discussed above do not have respective Wiki pages because they are implicit groups.
+To edit an existing group through the Wiki system, you can visit the group namespace through the Wiki "Index", and then choose the "Edit page" button.  If you wish to create a new group that has not already been created through the User Manager, you must visit the URL directly like this:
   https://wiki.cse.yorku.ca/mywiki/group:newgroup
-When you visit this URL, and click the "Create this page" button, you will be creating the group //newgroup//.
+When you visit the URL, and click the "Create this page" button, you will be creating the group //newgroup//.
 In addition to being able to modify group files manually, you can use some special syntax in order to allow you to include system groups (like ugrad or faculty), class distribution lists, other Wiki groups, or even combinations of all of the above.
-==== System Groups ====
+=== System Groups ===
 In order to manually add a system group to your group file:
@@ Line 37: / Line 45: @@
   include:system:faculty
-==== Class Distribution Lists ====
+=== Class Distribution Lists ===
 In order to manually add a class distribution list to your group file:
@@ Line 47: / Line 55: @@
   include:dist:2006-07:f:cse1020
-==== Other Wiki Groups ====
+=== Other Wiki Groups ===
 You can manually add other Wiki groups to your group file:
@@ Line 57: / Line 65: @@
   include:wiki:mygroup
-===== Access Control Lists =====
+==== Access Control Lists ====
 In general, most Wikis are very open by default.  However, sometimes it makes sense to restrict access to certain or all pages. This is when //Access Control Lists// (ACL) come to play. This page should give you an overview of how ACLs work in DokuWiki and how they are configured.
-Access restrictions can be bound to [[pagename|pages]] and [[namespaces]]. There are five permissions: //read//, //edit//, //create//, //upload// and //delete//. 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.
+Access restrictions can be bound to pages and namespaces. There are five permissions: //read//, //edit//, //create//, //upload// and //delete//. 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.
 When DokuWiki checks which rights it should give to a user, it uses all rules matching the user's name or the groups he is in. The rule which gives the highest permission is used. Permissions are checked for the page first, then all upper namespaces are checked until a matching rule is found.
-ACLs can be added in two ways.  DokuWiki comes with the ''Access Control List Management'' plugin which allows you to add restrictions to namespaces, and pages, but you must be on a page in the namespace that you wish to restrict in order to add restrictions to it.  Alternatively, our local DokuWiki installation has another plugin installed called "SuperACL" which lets you handle page or namespace restrictions to any page or namespace from one plugin, no matter where you are.  **SuperACL is the recommended plugin to use for Access Control List management. **  The rest of these instructions will focus on using the SuperACL plugin.
+ACLs can be added in two ways.  DokuWiki comes with the ''Access Control List Management'' plugin which allows you to add restrictions to namespaces, and pages, but you must be on a page in the namespace that you wish to restrict in order to add restrictions to it.  Alternatively, our local DokuWiki installation has another plugin installed called "SuperACL" which lets you handle ACL restrictions for any page or namespace from one plugin, no matter where you are in the Wiki.  **SuperACL is the recommended plugin to use for Access Control List management. **  The rest of these instructions will focus on using the Super ACL plugin.
-To add a restriction rule, enter the administration interface by pressing the ''Admin'' button (only available to the [[config#superuser]]). There select //SuperACL View//. You're then presented with a table like the following, showing you all restrictions relevant to the current page.
-{{wiki:acladmin.png|Example of an ACL-Restriction}}
-Restrictions are added in the top row of the table. You need to select the scope, which can be either the current page itself, or one of the namespaces it is in ((the top-most namespace is called ''*'')). You also need to choose who you want to give (or deny) access to; this can either be a group or a user. And finally, you need to select the actual permissions you want. Selecting none effectivly locks out the specified user or group from the page or namespace..
-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.
-=== Special Groups ===
-**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. For example, in the screenshot above, no one is allowed to upload, except members of the ''upload'' group.
-**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. Other than 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 another backend you need to use the groups provided by this backend.
-===== 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. :!: It is not recommended to edit this file manually. Use the admin interface instead.
-Empty lines and shellstyle 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// should never 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:
-<file>
-*                     @ALL        4
-*                     bigboss    16
-start                 @ALL        1
-marketing:*           @marketing  8
-devel:*               @ALL        0
-devel:*               @devel      8
-devel:*               bigboss    16
-devel:funstuff        bigboss     0
-devel:*               @marketing  1
-devel:marketing       @marketing  2
-</file>
-Lets go through it line by line (though see below for more):
-  - This sets permission for the main namespace. Allowing everybody to edit and create pages. However upload is not allowed.
-  - User //bigboss// is given full rights
-  - The permissions for the start page are restricted to readonly for everyone
-  - 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 his rights from line 2 so he can upload and delete files.
-  - 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 he's the only who can delete uploaded files
-  - However the devel guys don't want their boss to see the ''funstuff'' page -- remember exact pagematches override namespace permissions
-  - And the //marketing// team may read everything in the ''devel'' namespace, too
-  - And finally the //marketing// guys are allowed to edit the ''devel:marketing'' page as well.
-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 combi 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.
+To add a restriction rule, enter the administration interface by pressing the ''Admin'' button. Next, select //Super ACL View//. You are then presented with a table like the following, showing you all restrictions relevant to the current page.
-You can see this in the above example on the permissions for user //bigboss//. He is given full access in line 2, but needs to get full access for the devel:* namespace in line 7 again. If this line weren't there, the first match for user //bigboss// for a page inside the devel namespace would be line 5, because //bigboss// is member of the magic //ALL// group.
+{{wiki:acladmin.jpg|Example of an ACL-Restriction}}
-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. This only applies when a backend different from the [[.auth:plain]] one is used -- the plain backend does not allow any special chars anyway.
+Under ''Select namespace to administrate'', select the namespace that you will be configuring.  The top-most namespace is called ''*''.
-The DokuWiki manual describes the ACL system.  Basically
+After you have selected a namespace, under ''Permissions for Namespace'', you will see all the permissions that have been defined for the select namespace.  Here, you can change the permissions or delete them.  If you change the permissions without clicking the ''Update'' button, the permissions will not be saved.  If you wish to delete permissions, click the ''Delete'' button on the line of the permissions that you wish to delete.
-DokuWiki has been configured to
-In order to allow/disallow users on your site, you
-DokuWiki has
-  * authentication of CSE users
-  * built-in "cse" group for cse users, and "wiki" group for plaintext users
-  * "users" group is the default group added when no group is specified on adding an account
-  * groups can contain CSE users, system groups, or distribution lists
-    * include:system:group
-    * include:dist:session:term:course
-    * include:wiki:name
+If you wish to add an ACL entry to the selected namespace, go to the ''Add new Entry'' field.  Select ''User'' or ''Group'', enter the user/group in the field provided (eg. ''ALL'') , select the permissions, and click the ''Save'' button.  Selecting no permission effectively locks out the specified user or group from the page or namespace.
+Please note the following:
-By default, any user in the world has the ability to view all the content in your Wiki.  Administrators have access to edit content.  If you are satisfied with this setup, you don't need to change a thing.
+  * 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.
-If you need to restrict content on your site, you will be able to restrict content to groups that you create.  These groups can include system groups (eg. tech, faculty, ugrad), class lists, or even other wiki groups.
+  * **order does not matter** in the ACL. The ACL 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.
-ALL cse users are automatically registered with your Wiki and have the ability to login.   What they will see when they login differs based on how you setup the Access Control List.
+  * The admin of the site has access to everything on the site, no matter what the ACL says.
+  * By default, nobody has access to the ''group'' namespace (except admins).  **For security reasons, please be careful to ensure that you do not remove this restriction.**