changed git call from https to git readonly

[atutor.git] / mods / wiki / doc / ProtectedMode

Authentication in ewiki
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
If you'd like to restrict usage of your Wiki based on a user system and some
sort of permissions, then you may want to use the EWIKI_PROTECTED_MODE, which
enables additional access granting. (This is really optional, and won't have
any impact on the speed of ewiki if left turned off.)

The whole _auth interface stuff was implemented with flexibility in mind, to
allow ewiki to reuse any existing user authentication scheme already working
for yoursite (or used in the container CMS surrounding ewiki). That is why
this all will look complicated at a first glance.

While it is recommended to use the _auth interface for combination with an
existing user database (which most always requires to write your own plugin
to connect it with your user management system); it is for most people also
often satisfactory to just use one of the ewiki internal user database and
permission plugins that come as examples inside of the plugin/auth/ subdir.
You may want to give the user- and administrator-friendly UserRegistry plugin
a try if you don't already have a working user management system.


Leaving ewiki_auth() alone
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
If you just need a project internal Wiki or have only a small group of
active contributors, then you will often find it easier to just restrict
your Wiki using your Web servers .htaccess and .htpasswd method instead
(or see "fragments/funcs/auth.php" for the simpler inline solution).

And often your restriction desires may be matched by the two-wrappers method
described in the main README file - one public read-only Wiki view, and one
password-protected access for contributors.


interfaces
¯¯¯¯¯¯¯¯¯¯
The auth/ plugins are chained with the ewiki_auth() function, and restrict
access to the Wiki pages based on {meta} data or actions. The authentication
scheme is modular and divided into the thress basic abstractions / hooks:
- ["auth_perm"] is the main plugin function to check for access permission
- ["auth_query"] combines the user authentatication and login form printing
- ["auth_userdb"] can be used to retrieve a user entry or to verify passwords


    ewiki_auth()
    ¯¯¯¯¯¯¯¯¯¯¯¯
    Is called throughout the main ewiki script to request minimum
    permissions for the current $action and requested $page. This function
    chains to [auth_perm] and [auth_query] plugins to do its job. This
    function then just returns a boolean, stating if the permission plugin
    granted access.


    ewiki_auth_user()
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Queries all ["auth_userdb"] plugins (multiple may be there) for the
    given username and password, and returns (true) or (false) after
    comparing against the database entries` password fields.

    This function additionally sets $ewiki_auth_user if the password
    matches, and also $ewiki_author if it wasn't yet.


Variables
¯¯¯¯¯¯¯¯¯
$ewiki_author
    is only informational, but stored in each pages {author} database entry
    field. It is not required to have this variable set, it is just used as
    beatification for the database entries. If it was not set, then still IP
    addresses appeared in the {author} field of edited pages.

$ewiki_auth_user
    on the other hand is used in some of the distributed auth plugins to
    state that a user already was authenticated correctly. So this variable
    is not necessary, just a convinience interface to work around the
    completely functions-based _auth API.

$ewiki_ring
    could be used to allow permission granting from outside of ewiki,
    without writing any custom(ized) ewiki _auth plugin.


ring levels
¯¯¯¯¯¯¯¯¯¯¯
The so called "rings" are an optional simplification inside of the _auth
functions. Usually pages in ewiki are accesses pages using its name and an
action parameter, but it would to too much overhead to base permission
granting on both. So plugins like "auth_perm_ring.php" map $action/$id's
down to following "ring levels" to compare it against the current users
privilige level:

  0  -  is for "ADMINISTRATORS", allows actions like admin/ or control/
  1  -  means "MODERATOR" functions, like delete/
  2  -  for ordinary users or "EDITORS", which includes edit/ and upload/
  3  -  "GUESTS" can only view/ pages or view links/ and info/

While the "ring levels" are the built-in way to decide if the current
request is to be allowed or not, it is NOT the only possible. One could
still write a plugin, that completely skips the "$ewiki_ring" and bases
access granting on something completely different. However the ring levels
are also the default in the userdb plugins, and it is believed to be
satisfactory to have just four privilige groups/ levels, because otherwise
the user database needed to contain a bit mask or list of $actions which
were allowed for each individual user - what surely would be overkill. So
even if you tie an ewiki_auth plugin together with your already existing
user database, you may want to reduce it down to just these four permission
steps.

The $ewiki_ring variable makes it therefore also possible to connect your
existing userdb with ewiki without writing a customized ["auth_query"] or
["auth_userdb"] plugin, because if you just enable the _PROTECTED_MODE
and load 'auth_perm_ring.php', then $ewiki_ring decides about access
granting. So all you needed to do from within 'yoursite.php' was to set
$ewiki_ring to 2, and sporadically to 1 for a few "moderator users".


ewiki_auth plugin hooks
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
The ewiki_auth() function lets the ["auth_perm"][0] plugin decide about
access granting, if it finds one. It also calls the first ["auth_query"]
plugin before, and after the ["auth_perm"][0] returned false (but then
forcing to print a login form).

The ["auth_userdb"] plugins are not called directly from within ewiki_auth(),
but they get activated by ewiki_auth_user() which itself is called by some
["auth_query"] plugins (but they do not need to do this, if they know a
better way).

But please read the following plugin hook explanations first, if you go to
write your own customized ewiki_auth plugins:


    $ewiki_plugins["auth_perm"][0] ($id, &$data, $action, $ring, $forcelogin)
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Is called from within ewiki_auth(), and should return a value of 1 or 0
    if permission is granted. The plugin function should determine this by
    evaluating the current user name.

    The ["auth_perm"] plugin is itself responsible for retrieving the
    current username and fetching associated priviliges; but at least the
    user name can usually be found in the global $ewiki_auth_user or
    $ewiki_author (previously used therefore) variables. And for the
    "associated priviliges" the plugin could just concentrate on comparing
    an already defined $ewiki_ring (which eventually was set by a previously
    called ["auth_query"] or ["auth_userdb"] plugin) with the currently
    requested one in the "$ring" parameter.

    Often an ["auth_perm"] plugin will want to just look at the $action
    parameter to the currently requested page $id to make its decision
    (not all users should be allowed all $actions). However often it is
    easier to first map down the $action/$id parameters to a smaller set
    of privilige levels (like the 4 ring levels, how the 'auth_perm_ring'
    plugin does).

    If a perm plugin however is called with a $ring level request (this is
    the $ring variable is not NULL or false), then it MUST also take it into
    account (besides any other calculations on permission granting it
    already did).

    The $data parameter contains the internal array of the current WikiPage
    (as usual), and an ["auth_perm"] plugin could of course also use the
    {meta} field to store access granting informations (the owner name or
    even a password). Eventually the $data parameter is empty or only
    requires a few fields; then it may be desirable for the perm plugin to
    refetch the full database entry via ewiki_database("GET") before
    anything else. An appropriate check for this case was for example
    "if (count($data)<=5)".

    If the ["auth_perm"] plugin detects that access is to be denied, then
    it should put a failure message into $ewiki_errmsg.

    One could also write an complete ewiki_auth() replacement using
    this plugin hook, as all parameters for the original are passed
    over and only the boolean return value counts.

    Note: The default ["auth_perm"] plugin ('.../auth_perm_ring.php') only
    associates those "ring levels" to the different wiki $action tasks, and
    all real user authentication is done inside "auth_query" - but this is
    not required, and it's up to your fantasy to do it in a different way
    (separate login page and [auth_perm] just querying cookies for example).


    $ewiki_plugins["auth_query"][0] (&$data, $login)
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Is also called from within ewiki_auth() whenever the current users name
    is required and/or a login form could be printed into the current page.

    The fourth param $login (boolean) tells whether a login form should be
    printed (or some other mystic authentication should be started). This is
    important because $login=0 means to just check for a username and the
    password which may be currently already present in the httpd/cgi
    environment (in a Cookie for example).

    With $login==1 the plugin is asked to return a login <form> by writing it
    into the $ewiki_errmsg variable (unless you do some exotic authentict. 
    like http AUTH or access granting based on IP addresses). One could also
    put a failure notice into $ewiki_errmsg.

    An $login>=2 on the other hand can be used to explicetely enforce printing
    of the login <form>, even if an user was already logged in. (This then
    becomes the re-login hook).

    If you then retrieved a $username and $password inside your auth_query
    plugin (from wherever and regardless if $login=0 or $login=1), then
    your ["auth_query"] plugin should immediately compare it against a user
    database.
    To comply with the rest of the ewiki auth plugins, you should do this
    by calling ewiki_auth_user($username,$password) - which then just returns
    true or false, if the retrieved name and pw match anything inside of any
    registered user database. ewiki_auth_user() will then set $ewiki_ring,
    $ewiki_auth_user, $ewiki_author if the queried database contained that
    informations. Leave the $ewiki_errmsg alone if you let ewiki_auth_user()
    check the $password.

    You could of course let your ["auth_query"] plugin do all that work
    (comparing a $username and $password against an internal list, and
    setting $ewiki_ring when possible) - some people may find this far
    easier than chaining to ewiki_auth_user() or so, and this would allow
    you some more flexibility and reduces complexity.

    This function doesn't need a return() value - it is not evaluated. If
    you want to return something or inform some other parts or plugins, then
    use $ewiki_errmsg for <html> strings, or $ewiki_ring for basic access
    granting or invent another variable for later reevaluation by another
    function (your custom ["auth_perm"] plugin for example).


    $ewiki_plugins["auth_userdb"][] ($username, $password)
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    This is usally called from ewiki_auth_user() which itself got called
    from within an ["auth_query"] plugin (the auth_method_* plugins).

    Should return the user 'database' entry for the given user in the form
    array($encodedpassword, $ringlevel, ...) -  The returned $encpassword
    is afterwards compared by the ewiki_auth_user() function (usually
    invoked from within auth_query() plugins).
    The array should contain the $ringlevel for the queried user at array
    position [1], but it does not need to be there. Everything afterwards
    that in the array is ignored. So if there are other useful informations
    in your userdb entries, then the ["auth_userdb"] plugin should export
    this itself into $GLOBALS where useful.

    Alternatively an "auth_userdb" plugin could compare the $password
    itself or remotely against the contents of its database (and not let
    ewiki_auth_user() do that check). In this case it should fake the above
    behaviour by returning the $password as first entry of an array() in
    the form described above.

    The term 'plain auth_userdb plugin' (someties used in this README or
    plugin comments) refers to the more stupid variant that just returns an
    array() entry and lets ewiki_auth_user() compare the unencoded/submitted
    password against the checksum from the _userdb plugin.


Examples for your own ewiki_auth plugins
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

    Your own userdb plugin
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    If you have an existing user database and management system, you'll
    probably like to just reuse that one for ewiki. In this case you just
    needed to write a custom ["auth_userdb"] plugin.

      <?php
          define("EWIKI_PROTECTED_MODE", 1);
          define("EWIKI_AUTH_DEFAULT_RING", 3);    // read-only for unregistered
          $ewiki_plugins["auth_userdb"][] = "my_userdb";

          function my_userdb($user,$pw) {
             $result = mysql_query("SELECT * FROM users
                                    WHERE user='$user'");
             if ($row = mysql_fetch_array($result)) {
                if ($flags & USERFLAG_ADMIN) {
                   $ring = 1;    // moderator user
                } else {
                   $ring = 2;    // ordinary user, may edit/ pages
                }
                return(   array($row["password"], $ring)   );
             }
          }
      ?>

    In this example, we fetched the user data from a MySQL database table
    'users' with the rows 'name' containing the usernames, 'password'
    containing encrypted or unencrypted (?don't care) password. The 'flags'
    database column also tells wether the fetched user gets moderator
    priviliges (ring 1) or not (ring level 2).

    Most SQL user databases are layed out like this one, despite the
    fictional 'flags' column of course. If your database had an 'email'
    field as well, you could add this to reflect it:
      $GLOBALS["ewiki_author"] = $row["email"];


    Your own perm plugin
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    If you merge ewiki as just one piece into a CMS which already provides
    user authentication, then you could write a complete ["auth_perm"]
    plugin as replacement for ewiki_auth() like this:

      <?php
          $ewiki_plugins["auth_perm"][0] = "cms_permissions";

          function cms_permissions($id, &$data, $action, $rring, $login) {

             $user = & $GLOBALS["logged_in_user"];
          #  if (empty($user)) {  $user = CMS_Context::get_user_from_cookie();  }
             if (empty($user)) {  cms_print_login_form();  }
             $is_admin = & $GLOBALS["user_is_root"];

             $actions_allowed = array(
                "DEFAULT" => array("view", "links"),
                "root" => array("edit", "delete", "control", "admin"),
                "user2" => array("edit", "delete", "info"),
                "witch" => array("edit", "comment"),
                "..." => ...
             );

             $ok = in_array($action, $actions_allowed[$user])
                   || in_array($action, $actions_allowed["DEFAULT"]);
             $ok = $ok || $is_admin;
             if ($is_admin) { $GLOBALS["ewiki_ring"]=0; }

             return($ok);
          }
      ?>

    Instead of providing global variables your CMS may allow you to fetch
    user state/settings via a function or class API. However this plugin
    shows, how to ignore the $ring level stuff at all (but for the superuser
    you should set it, because admin/ plugins rely on it).


    No plugin at all
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Here's another example, on how to skip the 'plugin writing' thing
    completely by just setting $ewiki_ring whenever possible (you should
    then load the auth_perm_ring plugin).

      <?php
          $ewiki_ring = 3;  // view/browse/read-only Wiki

          if ($_COOKIE["username"] || $_COOKIE["LOGINSESS"]) {  // simple guess

             $ewiki_ring = 2;      // allows "edit" action and others

             if ($user_is_admin) {   // (already set somewhere else)
                $ewiki_ring = 0;     // this grants access to admin/ plugins
             }
          }
      ?>

    This is in fact the recommended way to do restriction stuff (the
    simplest solutions are always the best).


    Everything into auth_perm
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    As seen above the ["auth_perm"], ["auth_query"] and ["auth_userdb"]
    chains do not need to get implemented completely by your plugin;
    everything could be put altogether into just ["auth_perm"], as it is in
    fact itself responsible for retrieving the username and printing a login
    <form> when required.  If you don't have a separate login page you may
    then need to handle even password comparison herin.

    And as stated earlier it is the best option to use ["auth_perm"] for
    full customization of access granting, because it completely replaces
    the code of ewiki_auth().
    Because authentication frameworks like phplib intermix <html> output,
    session management, database queries, password checking and permission
    granting into a single API, writing a ["auth_perm"] plugin is often also
    the only possible way to combine them with ewiki.
    Not separating ["auth_perm"] and ["auth_query"] only may have the
    disadvantage, that the login <form> could appear more often than
    necessary. And you should therefore let users login before they browse
    through the Wiki, because phplib and alike are not very $_REQUEST safe.


Old notes
¯¯¯¯¯¯¯¯¯
When the wiki is in _PROTECTED_MODE, the core ewiki_auth() function is used
to check if the current user has permission to access the requested function.
Permission levels are called 'rings', but auth/perm plugins may restrict
access to functions also based on $action or page $id.

If you just want to restrict your wiki, you will often find it
easier to write two different wrappers around ewiki. See the
paragraph in the HowTo section on top of the main README.

The $ewiki_ring scheme is the built-in way to handle all permission
granting. Use this variable to separate users into the four groups:
guests (ring 3), ordinary users (ring 2), moderators (ring 1) and
administrators (ring 0).

While ring permissions fit most usage restriction needs, and are
the default and built-in way to handle restrictions, they are
neither important nor required. You could write a customized
"auth_perm" plugin, which operates on a completely different basis,
and ignore those "ring levels" at all. With "auth_perm" it is
possbile to grant permissions much more controlled (finer
associations), for example by comparing $action and page $id with
allowed values for any given user.


Available auth plugins
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
This is a short overview about the example auth/ plugins that come with
ewiki. Please note, that all plugin files carry comments on top, which
often give more detailed informations about how to use them; and you
may often need to edit some settings inside of them to suit your needs.

The most recommended plugins are currently:
 * auth_method_http
 * auth_perm_ring
 * userdb_userregistry
but alternatives are always a good thing.


    auth_method_form
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Provides a login request <form> like it is found in nearly all so-called
    ContentManagementSystems. It stores the retrieved data back into a
    browser Cookie once(!), after it was verified to match the user account.


    auth_method_http
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Uses the HTTP Basic AUTH method to query users for login informations
    (username and password), whenever it is needed. This is the recommended
    ["auth_query"] plugin; while it cannot be made fancy-looking at all, is
    more professional than the commonly found plain login <forms>.
    (With Mozilla and XUL/XBL coming up, there may well be possibilities for
    beatification of those otherwise boringly gray login dialog boxes.)


    auth_perm_ring
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Maps ewiki $actions (and also page $id's or combinations) down to the
    four basic ring/permission levels. Edit the config array() inside this
    plugin to change the mapping for existing or new plugin $action methods.
    Almost everybody wants to use this plugin for the _PROTECTED_MODE !


    auth_perm_unix
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Uses additional per-page UNIX-like "access rights" to map indirectly
    to ring/permission levels of registered users. It does not rely upon,
    but should be used in conjunction to one of the distributed simple
    ["auth_userdb"] plugins. It extends user management by providing user
    groups (which is not a core ewiki_auth feature, and won't become).

    The complicated internals are described in this plugins head comment.


    userdb_array
    ¯¯¯¯¯¯¯¯¯¯¯¯
    Provides the most simple/stupid internal user database - an array of
    usernames and passwords and permission/ring levels. This is useful if
    you only have a small group of active users, because it simplifies
    user management to editing this plugin file (adding users and changing
    passwords or permissions inside its PHP data array).


    userdb_systempasswd
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Accesses an user database inside of the ewiki database as _SYSTEM page
    "system/passwd". This page/file has a format like the UNIX /etc/passwd
    file; but contrates on usernames, passwords and ring/perm levels. The
    format of this ewiki page/file is described in the plugins comment.
    The _SYSTEM flag of this ewiki page/file requires an administrator user,
    which is the only one allowed to edit the "system/passwd" contents.

    To create (or edit) the page 'system/passwd' you will need to enter the
    appropriate URL manually: ".../wiki.php?id=edit/system/passwd", because
    the slash in the pagename makes it somewhat harder to find (ewiki else
    believes the "system/" to be an action parameter).


    userdb_userregistry
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Provides a ewiki database internal user/password list much like the
    above plugin, but additionally allows user registration and account
    management by non-administrators. The page "system/UserRegistry" then
    contains the user,password,permission data, and can only be edited by
    an ring level 0 user (administrator); while other users can go to the
    virtual page "UserRegistry" to register an account or to change their
    user settings (but of course not their permission level).
    You can easily tweak this plugin to store additional data inside the
    "system/UserRegistry" file for other uses.


    password_locks
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Is an ["auth_perm"] all-in-one plugin, that allows to attach one
    password to every page, which then locks the page for the user that
    knows it.


    you.php
    ¯¯¯¯¯¯¯
    Is an ["auth_perm"] all-in-one plugin, that is handy, when you only
    need the superuser/administrator account (like in PhpWiki).


    auth_phplib
    ¯¯¯¯¯¯¯¯¯¯¯
    Is an all-in-one ewiki_auth() plugin, that uses the 'phplib', which
    itself provides a user management framework and authentication
    functionality (<form> based). It adds permission management customized
    for ewiki. Please refer to this plugins comments, because it allows
    various customizations of course.


    userdb_anonymous
    ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
    Allows anyone to login using just an email address as password (should
    work with any ["auth_query"] user interface). Automatically grants ring
    level 2 permission, if it detects an address in the HTTP From: header
    field.


    users_ldap
    ¯¯¯¯¯¯¯¯¯¯
    Tries to login in a LDAP server using the given username and password
    for verification. Just an example for external auth.


    LiveUser
    ¯¯¯¯¯¯¯¯
    A plugin bundle utilizing the PEAR LiveUser authentication framework
    is separately available in the /plugins/auth-liveuser package, with
    its own README file. It is even much more sophisticated than our
    _perm_unix plugin, and provides user friendly administration pages.



Terminology
¯¯¯¯¯¯¯¯¯¯¯
administrator
    Is a userdb registered user, which has permissions of ring level 0.
    There exist multiple plugins, that are very dangerous to use (database
    admin functions), and should not be accisible to ordinary users or
    guests as well to not damage the Wiki setup or database. Therefore some
    plugins rely on ring level 0 (== superuser level).

editor
    Means an "ordinary user" with ring/permission level 2, which is at least
    allowed to edit/ (and then of course view/) pages.

guest
    An un/registered user in ring permission level 3 (which often is the
    default for EWIKI_AUTH_DEFAULT_RING).
    
moderator
    A user in ring level 1, which has all permissions of ring 2 and 3, but
    also can execute more dangerous page actions like page delete/ or so.

_PROTECTED_MODE
    this name is in fact used as joke here, the term origins from the
    "virtual protected address mode" introduced in the i386/486 family cpus
    in the late 80s (which is/was the basis for NT/Linux)

ring levels
    are connected to the "protected mode" joke, the 386 cpu also used
    those ring levels (also in the range 0 till 3)

superuser
    Means the same as "administrator" or "root" (these terms in ewiki of
    course do not refer to your computers filesystem).


Problems
¯¯¯¯¯¯¯¯
ewiki_auth sometimes fails, because it tries to perform authentication first
when it is actually needed (unlike other systems, where you get annoyed with
the login <form> before you had the chance to see any page at all).