PmWiki | Cookbook / UserAuth2

Summary: A user-based permission granting and authentication module

Version: 2.1-beta4 (2009-01-03)

Prerequisites: PHP >= 4.3.3 (for having a sufficiently working session support); Cookies enabled

Status: released, stable, maintained (tested with Pmwiki 2.1.11, 2.2.0-beta45)

Maintainer: ThomasP

Overview

This is an authorization and authentication module for the pmwiki engine, originally intended to be a reimplementation of the Cookbook.UserAuth module. It provides a flexible way of granting permissions on a per-user basis via a typical web interface, and password or - subsequently - cookie based authentication. The main motivation was to fix the bugs in the former module systematically and on the way introduce the possibility of sharing/delegating administrative tasks (like creating users, assigning them permissions) with other users. See a complete list of changes compared to the former module here. (LDAP support was added in version 2.1-beta2.)

Live showcase

I have put up a live example of this module at http://www.sigproc.de/ua2_showcase65/. A sub admin account can be accessed via username "small_admin", password "pmwiki". It allows access to the admin tool (click "Admin tool" next to the action links), creation of users and unlimited access to groups starting with "Test".

Files

userauth2.1-beta4.tgz Δ (2009-01-03) (includes security fixes) (Changelog, Known issues)

containing:

 userauthx.x-stable/
   README.userauth2
   LICENSE.userauth2
   UPGRADE.userauth2                <- find information about how to upgrade here
   userauth2.php
   userauth2/
     .htaccess
     UserSessionVars.php
     userauth2-permchecklib.php
     userauth2-admintool.php
     userauth2-pwchange.php
     userauth2-bruteforce.php
     Site.Login
     UserAuth2.EditUserQuickReference

Installation

Unzip the package file and copy the contents to the cookbook directory. Move the file userauth2/Site.Login to wiki.d/ and userauth2/UserAuth2.EditUserQuickReference to wikilib.d/. Add

 $HomePage  = "Main.HomePage";       // should use dots (instead of slashes) even when using
 $LoginPage = "Site.Login";          // CleanUrls ($EnablePathInfo=1)
 $HandleAuth['diff'] = 'history';
 include("$FarmD/cookbook/userauth2.php");

to your local/config.php and adapt the home page setting to your needs. (It is needed for some default redirection.) The login page can be renamed/moved around BTW (provided you adjust the local/config.php), but make sure it is non-editable. The HandleAuth line can be omitted if no designated permission level for accessing the page history is needed.

Upon the first run of the module, an 'admin' user will be created with a default profile containing an empty password. Change this later, e.g. by calling

 http://www.foo.bar.com/path/to/my/wiki/pmwiki.php?action=pwchange

while logged in as 'admin'. Besides a guest user group will be created, with read-all access (except for the SiteAdmin group) set as default. You can change this as you like. You can also define a group "LoggedInUsers" whose rights are granted--as the name suggests--to all users that are logged in (i.e. are identified to the system with non-empty user name).

That's it. I have put up some help below on how to get the permission setup started. As the module slowly starts to mature, I expect no immediate bugs to be discovered anymore. If there still should be one, or if you have questions/suggestions, leave a comment below or ask on the pmwiki mailing lists (usually pmwiki-users is best). For development related details it might be also useful to contact me directly (email can be found here).

Remark

To ensure a defined session expiration behaviour and for various security reasons, this module directly sets the session save path to a sub dir in the userauth2/ dir. (This directory will be automatically created.)

Useful markup

To get some login/logout links, the following markup might serve as example:

(:if loggedin:)
* [[Logout ({$AuthId}) -> {$FullName}?action=logout]] \\
(:if:)
(:if ! loggedin:) 
* [[Login -> {$FullName}?action=login]] \\
(:if:)
(:if auth admin :)
[[{$FullName}?action=admin | $[Admin tool] ]]
(:if:)

Simple usage

Setting permissions is done by manipulating the permission tables of the various users/groups. For this call up the admin tool via

 http://www.foo.bar.com/path/to/my/wiki/pmwiki.php?action=admin

while being logged in as admin (or as someone who has admin tool rights). Then, to grant rights specify a list of permission entries in the permission table of the respective user (create a new user first). The common entries take the form

 LL_ggg.ppp

where LL is rd, ed, up or hi, denoting the permission levels read, edit, upload and history. (Here "upload" means that the user may upload files to the dir corresponding to this page, and "history" that she may view the history.) You can also use xx which matches all page related levels. The ggg.ppp is the part specifying for which page the right should be granted. You can use typical wild cards to target a set of pages/groups.

Prepending the whole entry with a '-' (minus) exactly withdraws the right. For this purpose the entries in the permission table are interpreted in the order they occur, with the final applicable entry setting the result.

For example a typical guest user permission table might look like this (this is a suitable permission record for pmwiki 2.2.0-beta58 or above, previous example here)

rd_*.*,
-rd_SiteAdmin.*,
ed_Home.Feedback,
xx_Playground.*,

It makes the whole pmwiki readable, with exception of the 'SiteAdmin' group which is reserved for pages intended not to be publicly available (since pmwiki 2.2.0-beta58). Additionally a feedback page is editable, while the complete Playground group is freely accessible.

Help on options / advanced features

Find documentation on the topics below on the documentation page.

How to authenticate against a LDAP server
How to set up ip based silent permission granting
How to set ip based login restrictions
How to change the default redirections after login/logout
How to enable/customize persistent logins
How to disable/customize brute force attack prevention (enabled by default)
What wild cards can be good for
How to create personally accessible pages (using {$AuthId})
Delegating permission granting / Multi admin setups
How to introduce new permission levels for certain actions, like for "publish", "comment" etc.
How to change one's own password as a user

Bugs

If you discover a bug in the system and like to do some debugging, you might consider getting my debugMsg() function (can be found at ThomasP). With this you can use the internally already set up debug facilities.

In general when encountering a bug, have a look at the KnownIssues first, and have a light skim over the mailing list archive to see whether something is said about it already. When reporting, please quote your pmwiki and PHP version.

If you like to contribute to development and have some larger comments, please leave them on UserAuth2-Talk.

Contributors

ThomasP (original version)

Small user survey

I'd like to know who is actually using this module. Just manually count up numbers:

new user (first time at pmwiki for no more than 3 months): 16
"old" user: 9

(started April 2007)

Comments

This space is for User-contributed commentary and notes. Please include your name and a date along with your comment. Optional alternative: create a new page with a name like "ThisRecipe-Talk" (e.g. PmCalendar-Talk). See Discussion at UserAuth2-Talk

The skript works very well - great work! But when I want to login with setting a cookie the following is returned:
Fatal error: Call to undefined function: get_rand_session_id() in [...]\cookbook\userauth2\UserSessionVars.php on line 200 How can I fix it? Tx a lot! Michael November 16, 2007, at 03:04 PM
Fixed it by replacing line 200 in UserSessionVars.php by $randKey = microtime();. It works, but I guess there shall be a more professional soulution. :-) Michael ? November 17, 2007, at 02:03 AM

Thank you Michael, it is quite astonishing that this error had not been arisen before. (Though I personally use the module currently without cookie authentication.) The function referred to an old setup with a separate session implementation. I have added the missing code (a pure arbitrary choice of mine for a good rand key generator BTW), starting from version 2.0-beta9. See changelog for the new code. ThomasP November 28, 2007, at 12:25 AM

Hope this isn't a stupid question, but where exactly does the permission table content go - in Site.Login, the userauth2 php file, somewhere else? I took a look at UserAuth2.ExampleSetups and it also does not say where one would place the settings. Thanks for any help. -Matt

For the user or group you want to give the permission to click on edit.

In the form displayed there is a box Permissions granted by. table content goes here.

I had to think about this, but it works well -Dave

Yes! Thanks for the help, all good now. -Matt

It seems that my 'http://url.com/pmwiki/pmwiki.php/Site/Site?action=admin' has bad links all around. Could it be because I set "$EnablePathInfo = 1;" ? All the links on that page are rendered 'http://url.com/Site/Search' or url.com/Site/Site?action=edit < all dead links. Thanks - Kevin - Profiles

Hello Kevin, the problem should be solved with version 2.0-stable5. The reason for the search links appearing was that $ScriptUrl was unintentionally overwritten by UA2. ThomasP May 27, 2007, at 05:46 AM

I am trying to implement the UserAuth2 and I am having some difficultly. I have my user with admin rights but whenever I type in the password, it displays the "incorrect password" message. It should be the correct password, I say this because earlier I was able to change it from xxxx to yyyy and it was saved successfully. Any ideas?

Hi! This could have many reasons. First it is important to know that "Wrong password" is shown also if actually the user name is wrong, or when the ip address of the client does not match the allowed login ip range (if you have set sthg like this). Can you have a look in the admin profile file to see whether the change has actually taken place? (BTW, let's take it to the pmwiki-users mailing list, otherwise I might not become aware of your answer.) ThomasP July 24, 2007, at 05:41 AM

Hi, I always lock myself out when editing users/groups: "Cannot proceed. This record is locked by someone else for editing. Please try again later.". Because of trouble with my hoster (disturbing error comments) I uncommented all lines beginning with ini_set in userauth2.php (about five around line 210). Could this be the source of the error? peter February 26, 2008, at 12:14 PM

The error message is: "Warning: ini_set() has been disabled for security reasons in /usr/export/www/host...." and from what I understand big part of the cookie game is managed in these 5 lines. Any ideas for work around? peter February 26, 2008, at 12:49 PM

It's not the cookies. The 5 mentioned lines can be discarded. But I found files called after the locked out groups in the userauth2/groupperms folder. They seem to have timestamps. Deleting them solved the problem.

Hello, seems I'm fortunate enough to come along when the problem is already solved. Usually the locks are applied to prevent multiple admins to edit a record of one user at the same time. Usually these locks are deleted upon logout, edit cancel, or simply disregarded if old enough. The question is your case would remain why it did not work in the beginning, but then later.

The ini_set lines adjust the absolute lifetime of the php session files to 24h (rather than 24mins default). Note this is only (the inflated) part of the mechanism, the authorative time management is done in the userauth2.php script "manually" in order to be reliable. (The PHP implementation is prohibitively sluggish with respect to session expiration.) ThomasP March 26, 2008, at 02:41 PM

Hi, after i installed the package I get the following errors..
Notice: Session table unacceptable in /www/global/script/sessions.php on line 88
Warning: mysql_real_escape_string() expects parameter 2 to be resource, null given in /www/global/script/sessions.php on line 108
(plus I dont think I have farms enabled. Im just looking to add basic user authentication to my new pmwiki install)

"Unfortunately", there is no sessions.php in this package, and I have never used the function mysql_real_escape_string(). ;-) ThomasP March 26, 2008, at 02:44 PM

Hi, I'm a little bit confused with the parent and group settings. From my understanding, if you want to create a 'Editor' group, you need to:

Create a user called 'section_a_editor', granter 'admin', with the limited rightsets specified
Create a group called 'secton_a_editor', granter 'section_a_editor', with the same rightsets as above

Later on, you want to create a new editor for section A, you can

Create a user, granter 'section_a_editor', rights '@section_a_editor'

Is it correct? What is the use of 'group' actually? A shortcut to a rightsets?

The use of groups is indeed to provide a way to collect a certain right set and then be able to reference this set from various users by adding e.g. "@Section_A_Editor" to their permission list. It is not necessary to create a dedicated granter for this. The administrator can both create and edit the group "Section_A_Editor" and edit the permission records of relevant users. This should suffice for most of the cases.

The use of the granter field/ multiple granters is to allow more than one person (beyond the Administrator) to set permissions for a single user, while keeping these granting privileges separated. (The "second admin" would and should not be able to change what the first admin set for the user. Obviously.) This way one can realize real delegation of admin work, e.g. set out responsibility areas in the wiki (e.g. page groups) which are governed by different persons. ThomasP July 10, 2008, at 07:56 AM

Hey, is there a way for users to register themselves?

thanks

Ben - May 11, 2008, at 03:14 AM turned dot 111 at gmail dot com

No, unfortunately not, at the moment. There was a solution once for UserAuth (the former version) (not compatible or reusable), which might give some insights into what is useful/necessary to be implemented. I have not anymore all these aspects on my mental screen at the moment. (But for example, to avoid bots registering, some captcha mechanism would be necessary.) To think loudly, my spontaneous idea would be to use indeed the Pmwiki forms, together with a function called by dedicated markup to actually add the user. I'm not proficient with Pmwiki forms, but would write the second part if the interest is still there. ThomasP July 10, 2008, at 07:56 AM

I cannot figure out what page a user should go to in order to update their password. (I set a user with the pw permission, but don't know how that user would actually go about changing things, since I don't want to give them permissions to the main admin page.) Thanks in advance... the plug-in overall is quite cool.

Answered my own question. Append ?action=pwchange to a URL. Now, where to put this in the docs... (done, ThomasP October 02, 2008, at 12:53 PM)

metahacker

Hey, is there a way to reset the admin password afterward (I forgot it...)?

thanks

Plog - July 19, 2008

Hello, yes, though with some dirty editing. Passwords are stored among other things in the profile of the user, see userauth2/profiles. In the serialized PHP array, find the "password" field and replace the value (with me a 34 character string starting with $) by the output of the PHP crypt function (use the ?action=crypt to get that for your newly chosen password). ThomasP

October 02, 2008, at 12:53 PM

I love this recipe, but I found one issue and me being a noob I must have missed something. I don't see where to add users anywhere. Did miss something somewhere?

Thanks AJ - Roctober, 29 2008

When logged in as admin, go to the admin tool and scroll down to the end of the user list. There should be a button "add user" as last line in the table. Furthermore, in the extended use of the module, also certain non-"super-admin" users can add users (which will be seen as a kind of their children). For users to be allowed to add (create) users, they will have to have a cu entry in their permission record.
On the other hand, you might also have thought of users signing up to the wiki themselves. This is currently not possible. ThomasP December 23, 2008, at 09:02 AM

UserAuth2