====== aclauditor Plugin ======

---- plugin ----
description: Gives info about users/groups/pages permissions, like how they are constructed, and allow to test ACL against scenarios
author     : Etienne Meleard
email      : etienne.meleard@free.fr
type       : Admin, Syntax
lastupdate : 2010-09-24
compatible : Lemming
depends    : 
conflicts  : 
similar    : aclinfo
tags       : acl, audit

downloadurl: https://trello.com/1/cards/5bc2138261e6091620e2b992/attachments/5bc213a70da3cb2833dfe4cc/download/aclauditor.zip #http://dokuwiki.yent.eu/aclauditor.zip
bugtracker : 
sourcerepo : 
donationurl: 
----

^ Compatibility with DokuWiki release Binky: works basically, but some features (?) won't do since outdated use of [[devel:jqueryfaq#addinitevent]]^

===== Download and Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

===== Syntax and Usage =====

==== Goal of this plugin ====

This plugin intends to help wiki admins to answer questions like "How is it possible that this user can edit this page, I must have messed up permissions, but which line is causing that ?" or "How can I ensure that my permissions are set properly ?".

It proposes several features :
  - A way to list permissions for a user or group
  - A way to list which permissions apply to a page
  - A way to view how a permission for somebody to do something on a page is constructed
  - A way to test permissions against a set of rules that must be respected to ensure integrity, such set will be called scenario

It was created at the Dokuwiki hackfest during FrOSCamp 2010, special thanks to Guy Brand for ideas regarding the scenario mode.

==== From Admin menu ====

=== "Simple" mode ====

In this mode you can list permissions of a specific user or group (if none given then current user is used), list permissions applied on a specific resource (page or media) (similar to the default permission management, except that you cannot set permissions) or view how a user/group get its permission on a resource through permission inheritance pattern (and then track which permission record is messing the whole thing).

If you want to enter a group you must prepend it with the @ symbol.

== User/group test ==

The results will show, for each resource there is an ACL record for, the list of permissions that the user/group owns and the final permission on the resource according to inheritance rules.

== Resource test ==

The results will show all ACL applied on the resource.

== Permission detailed construction ==

This mode tells you in which way a permission for a user/group on a resource is constructed through inheritance patterns and specific matching rules.

=== "Scenario" mode ===

In this mode you can test your ACL config against a list of rules (or scenario). The scenario is a simple csv file which lines look like :

  resource_id,user,groups,value

  - **resource_id** is a dokuwiki id like foo:bar, it accepts pages and namespaces (foo:bar:*)
  - **user** (optionnal) user identifier
  - **groups** (optionnal) is a pipe ("|") separated list of groups (without the @ header), or empty if groups musn't be tested, or wild-card if all groups the user is in must be taken into consideration
  - **value** is the awaited permission, it consists in an optional comparator and a integer

Examples :
  foo:bar,joe,*,1  => checks if user joe or any of his groups gives him a "read" permission on page foo:bar
  foo:bar,joe,dev|prod,>=4  => checks if user joe, the dev group or the prod group get at least a "create" permission on page foo:bar
  foo:bar,joe,dev,!8  => checks if user joe or the dev group do not get a "upload" permission on page foo:bar
  foo:*,joe,,<2  => checks if user joe, without taking consideration of his groups, gets less than a "edit" permission on namespace foo

The scenario can be server side stored in order to use it later. The plugin accepts comma separated and semicolon separated CSV as well as quoted fields. Note that lines whose first field starts with the # symbol is considered as a comment line, if the first line is a comment line and if only its first field is filled it will be considered as the file description.

Server side stored scenarios are saved as csv files under the DOKUWIKI_ROOT/conf/aclauditor_scenarios directory.

== Value comparators ==

^  comparator  ^  meaning  ^
|  = or ==  | is equal to  |
|  ! or !=  | is not equal to  |
|  <        | is less than   |
|  <=       | is less than or equal to  |
|  >        | is greater than  |
|  >=       | is greater than or equal to  |

== Scenario example ==

  # Scenario to test that the dev group have the good permissions,,,
  # id,user,groups,value
  doc:*,,dev,16
  dev:*,,dev,16
  # only joe can update news,,,
  news:*,joe,dev,4
  # dev group musn't get access to foo:hidden_to_dev page
  foo:hidden_to_dev,,dev,<1

==== Inside a page ====

You can use the following syntax inside pages :
  <ACLAUDITOR [options] />

It will display a "test acl" button to wiki admins that will allow them to do quick testing. The available options are :

^  name        ^  meaning  ^  example  ^
|who           | view permissions for user or group    | ''<ACLAUDITOR who=joe />''\\ ''<ACLAUDITOR who=@dev />''  |
|what          | view permissions applied on resource  | ''<ACLAUDITOR what=foo:bar />''\\ ''<ACLAUDITOR what=foo:* />''   |
|who and what  | describe permission for user or group on resource  | ''<ACLAUDITOR who=joe what=foo:bar />''\\ (this is just a combination of the previous ones) |
|scenario      | run a set of test rules from a scenario file       | ''<ACLAUDITOR scenario=scenario_for_dev.csv />''\\ (the value can be omitted to just create a shortcut to the scenario test mode page) |

===== Discussion =====

> Please check. I think, the @ALL-group is ignored on using "Get ACL applied on resource"?