ExternAuth

Summary: Use authentication mechanisms external to PmWiki

Version: 0.1, 3 June 2006

Prerequisites: Last tested on PmWiki version: pmwiki-2.1.5

Status:

Maintainer:

Question answered by this recipe

ExternAuth enables PmWiki to utilize authentication mechanisms external to PmWiki by accessing php $_SESSION variables set by the external authentication mechanism:

$_SESSION['authenticated'] - a BOOLEAN
$_SESSION['username'] - the username of the authenticated user
$_SESSION['groups'] - an array of groups for which the user is a member.

Page attributes can be set to allow access based on individual users, groups of users, or open access. The attribute edit form has been changed to allow users to select groups using checkboxes. Additionally, WikiGroups can be given default authentication requirements for individual actions for all pages within the group. That is, one can set a WikiGroup to be readable by all, and editable only by authenticated users. Then, on a page by page basis, these defaults can be overridden.

Additionally, the username is used as the Author name for all edits.

Files

Description

The ExternAuth module assumes that (for whatever reason), authentication is being handled outside of PmWiki. Whatever authentication mechanism is being used, it is assumed that the php $_SESSION variable is set. The following variables are set in the $_SESSION variable:

$_SESSION['authenticated'] - a BOOLEAN
$_SESSION['username'] - the username of the authenticated user
$_SESSION['groups'] - an array of groups for which the user is a member. These are set in the ExternAuthGroups variable later in the file.

This file changes the AuthFunction to ExternAuth, which uses the $_SESSION variables to validate a page based on the externauth variables set for the page and group.

Much of this file is simply copies of functions from PmWiki with slight modifications for the extern authentication.

ExternAuth sets variables on pages where the variable name is: externauth_{level}_{mode} where the level is the action level requested - read, edit, attr, etc., and the mode is one of allow, group, or user. The allow variable is a boolean that allows access to anyone. The group variable contains the different groups that can access the page, and the user variable contains the different users that can access the page. Therefore, pages are granted access based on the settings. Access is given to all, any number of groups, or any number of users. There is currently no capability for authentication exceptions (like everyone except fred). If nothing is specified, the ExternAuth module has an ExternAuthAttribute function set for each attribute. These can be set to pass the authentication on to the underlying PmWiki Auth functions, or do whatever the user might want to do based on other $_SESSION variables.

Installation

Download the externauth.php Δ file to your cookbook directory.
Include the plugin from your config.php file:

require_once("cookbook/externauth.php");

For an example of a group variable definition file, download ExternAuthGroupVars.php Δ to your local directory.
Include this file from your config.php file:

require_once("local/ExternAuthGroupVars.php");

Usage

After installing externauth, some external authentication mechanism must be employed that sets the appropriate php $_SESSION variables. The attributes for each page can be accessed using the php variable ?action=attr in the URL (http://www.pmwiki.org/wiki/Cookbook/ExternAuth?action=attr). Note that the link above does not have the attribute page given by this module, as ExternAuth is not installed on the PmWiki site.

By default, the read and edit actions are passed through to the underlying PmWiki authentiaction mechanism for authentiaction. There are special functions in externauth that provide functions to specify the defaults for other attributes - refer to the ExternAuthAttributes hash in the code. Also, edit the ExternAuthGroups hash to define the groups that show up in the attributes page.

The group variable definition file above provides a special default for wiki groups named after the authenticated user (http://mydomain.com/wiki?n=myusername/...). For these groups, the authenticated user is given complete authority over all pages in that group.

The code may not be as generalized as some might like. After all, it was written by a hardware guy, so it is effective, but possibly not quite as beautiful as some might hope ;-).

History

June 3, 2006 - Version 0.1
- Initial version

Contributors

GarySpivey ? - Original author

Copyright

Comments

See discussion at ExternAuth-Talk ?

User notes ? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.