Note: The recipes here are for PmWiki versions 0.6 and 1.0 only. For PmWiki 2.0 recipes, see Cookbook.


To create greater access control for PmWiki installations where the admin does not want the whole world able to change pages or wishes to only allow select users to have editing access.


(See History below for version differences)

Distribution unzips with these files:


This PmWiki plugin makes it possible to restrict access to the entire wiki by requring a username and password for certain actions. Individual pages and groups can still be password restricted in the same way that PmWiki does by default. However, user authentification happens before wiki password authentification. Additionally, the username doubles as the author name.

By default this plugin reads username, password and ability information from a .htpasswd file. This file is created when the script is first run in the PmWiki "local" directory with the default restrictions that non authorized users can only read pages. The htpasswd file has an additional third field where abilities are stored. This field should not interfer if you wish to use the same htpassword file with Apache basic authentification. A typical htpassword file would look like the following:


The abilities field is a list of actions the user can perform separated by commas. Abilities correspond to the same type of actions defined by PmWiki in the $DefaultPassword array as well as some custom actions:

PmWiki Actions:

  • admin, attr, edit, read

UserAuth Actions:

  • admin - Admin is also checked explicitly by this plugin. This allows an admin user to be able to access any PmWiki password protected page without supplying the password.
  • read_all - Allows the user to read any page, even if it is read password protected.
  • read_group-GroupName - Allows the user to read all pages in GroupName, for example: read_group-PrivateArea


  • Unpack the distribution file into your PmWiki local directory
  • Include the plugin from your config.php file:
  • Load your PmWiki once to create the default .htpasswd file
  • Modify the created .htpasswd file to include a user that has "edit" ability. Use your wiki to create the password by appending ?action=crypt to the url to load the PmWiki password encryption page. Create the user's line in the htpasswd file in the usual Apache htpasswd format but make sure to add and extra field to contain the user's abilites. See the description above for an example of how to format the file.
  • Create the page Main.LoginPage so that the login page will show up within your wiki layout, otherwise a default standalone page will be used. Simply put the following on Main.LoginPage:
Main.LoginPage is just the default and the login page can be changed to whatever you like. See the configuration details below.


The following variables can be defined before userauth.php is included in in config.php:

$GuestUsername - Specifies the username that is used by default when no user is logged in.

$LoginPage - Name of the page which has the "<#>" double bracket code on it to display the login form.

$LackProperAbilitiesFmt - Message displayed when the user unsuccesfully tries to login.

$AuthPageTitle - Title of the standalone page showing the login form.

$HtPasswdFile - Alternative location of the HtPassword file. Not used if $UserInfoObj is set before the script is included in config.php.

HtPasswd.php will be used to grab user information unless the $UserInfoObj is already set. This allows someone to write a new user info object that gets its information from a database or some other format. This new class would only need to implement the same minimum contract that HtPasswd.php does

The HTML that is displayed on the LoginPage can be easily changed. By default the <#> inline replacement calls a function that returns the login page. To specify different HTML then either redefine the definition of <#> in the $InlineReplacements array or use some other method that correctly calls the login action.

If you wish to change your template to include a link that displays "Login" or "Logout" depending on whether or not a user is logged in then add the following to the template:

<a href='$PageUrl?action=$LoginAction'>$LoginName</a>


September 12, 2004 - Version 0.1 - Initial version
November 22, 2004 - Version 0.2 - Added ability for allowing a user to view an entire view password protected group, as well as many other clean ups and improvements to code.

Comments & Bugs

Anybody get this to work at all? A friend I have been trying for the past hour to get this thing to work and no matter what we've done, it always says "Insufficient Privilegdes" for any username/pass we try with any attribute we try. and you have to log in to access the site, even though it made a guest login in the default .htpassrd file

I can't get this to work either, I have the same problem. I have tried checking out the php code, but I can't see any reason for why this is happening. Please check out your code! This is valuable functinality that I could really use. Thank you, Corbin [(approve links) edit diff]

I just uploaded a new version with some fixes and improvements. Try using that and if you still can not get it to work then add print statements in userauth.php to help you figure out where it gets the authorization denied. If you find a bug then please let me know! - James McDuffie

I've got it to work for the usual cases, but what do you set up in order to get the Development/RssGeneration to work? I've tried the obvious rss but no luck.... - /blader_se

The problem with Development/RssGeneration is that the scripts/rss.php code does not correctly call the RetrieveAuthPage function. It does not send the level of authorization to the function. To fix this change the following lines in scripts/rss.php:

 $page = RetrieveAuthPage($pagename,false); 
$page = RetrieveAuthPage($t[$i]['name'],false);


 $page = RetrieveAuthPage($pagename,"rss",false); 
$page = RetrieveAuthPage($t[$i]['name'],"rss",false);

Then add an ability into your .htpasswd named rss. For instance to give everyone the ability to retrieve rss files make your guest user entry look like this:

Thanx - it now works great! /blader_se \\Can sombody give an example how it should work?
I only have an Fatal error: Call to undefined function: starthtml() in userauth.php line 282 Thanks



Copyright 2004, by James McDuffie under the GNU GPL License pmwiki-2.3.7 -- Last modified by {{Matthias}}?

from IP: ip should be disabled by default for security reasons