PmWiki | Cookbook / HtpasswdForm

Summary: .htpasswd/.htgroup file editor

Version: 2008-07-28

Status: Stable

Prerequisites: pmwiki-2.x

Maintainer: Dfaure

Question

(I'm currently using identity-based authorization / AuthUser configuration, and ...) I need a convenient tool to edit / manage .htpasswd and/or .htgroup file(s). Is there such tool available within PmWiki?

Answer

Download htpasswdform.php Δ and save it in the cookbook directory.
Add include_once("$FarmD/cookbook/htpasswdform.php"); in a Local Customizations file, for example local/Site.HtpasswdForm.php
Edit the corresponding Wiki page (Site.HtpasswdForm ? in the given example) and add the (:htpasswdform:) directive to manage your .htpasswd and .htgroup files,…
…and don't forget to protect the wiki page access according to your needs!

Notes

This recipe provides simple but effective form-based tools to maintain .htpasswd and .htgroup files, when used as PmWiki authentication scheme or not, ie, with the appropriate configuration this recipe could be used as a "stand-alone" (not pmwiki related) file editor.

It should also be noticed that even if the .htpasswd/.htgroup specifications is to allow usernames/groupnames containing spaces and quotes or even empty passwords, PmWiki is still unable to handle them. Some configuration parameters have been made available to meet PmWiki requirements. See below for details.

The htpasswdform_improved.php Δ script has been *officially* deprecated. See History.

Forms

According to user rights the directive will render as full editor, a simple password changer or even a new user registration tool:

non-functional regular user sample form:

For security (and simplicity) reasons, the password changer form will only give feeback messages to successful updates.

non-functional admin sample form:

The exact aspect and features of the form below will depend on the recipe configuration parameters.
Except for the two Create... buttons, The form buttons are usually acting on the selected user or group record in the list immediately above (radio button).
The new group, user definition, username, password or comment values are retrieved from the related fields immediately below.
The user-password should be typed twice to be validated. Generated password encoding may be selected with the associated radio buttons (apr1 format is required on Win32 platforms to maintain the compatibility with Apache environment).
Users may be managed individually or globally to the selected group with the appropriate button (Add a User, Remove a User or Set all Users) and the beneath field contents.
With an empty field, the Add a User and Remove a User buttons will use the currently selected user in the .htpasswd user list (configuration dependent behavior).
When the update group(s) checkbox is enabled, renaming or deleting a user in the password editor will also update the group definitions. New users will be automatically added in the currently selected group (configuration dependent behavior).
Altering the default configuration parameters (see below), the form may even be configured to let unauthenticated new users to self-register, and if detected, can make use of the Captcha recipe.

Configuration variables

The following variables need to be initialized in the Local Customizations file, before the include_once("cookbook/htpasswdform.php"); directive:

$EnableHtpassword, $EnableHtgroup

Enable/Disable related file handling (defaults to 1 or 0 according to the definition of the two following variables).

$HtpasswdFile, $HtgroupFile

Allows to select the working .htpasswd/.htgroup file:

If not explicitely set, they defaults (in the given order) to:

the 1^st file(s) encountered in the AuthUser configuration you may provide in local configuration files as:

# Use local/.htpasswd for usernames/passwords
$AuthUser['htpasswd'] = 'local/authuser/.htpasswd';
# Use local/.htgroup for group memberships
$AuthUser['htgroup'] = 'local/authuser/.htgroup';
include_once("$FarmD/scripts/authuser.php");

or lastly, the equivalent definition provided into the Site.AuthUser page.

On Un*x, you should also make sure that the user running the webserver (usually "www") has the right to write the password/group file(s).

$HtpasswordAuth

Selects the privilege level switch between the two forms (defaults to "admin").

$HtpasswordNewUsers

When set to 1, a new user form is provided to unauthenticated users, allowing them to register themselves (defaults to 0).

$HtpasswordCaptcha

When set to 0, disables the optional new user form captcha (defaults to 1).

$HtpasswordAutoLogin

When set to 1, allows new users to be logged in once being registered (defaults to 1).

$HtpasswordNewPageRedirect

The page name where newly registered users are redirected automatically (defaults to current page).

$HtpasswordForms

An array providing the forms used for password change and new user registration.

$HtpasswordDefaultType

Selects the default password encoding scheme (defaults to 0, aka apr1). Usable schemes are (as stated in the Apache documentation):

Scheme	Type
0	`apr1` - The MD5 algorithm used by htpasswd is specific to the Apache software; passwords encrypted using it will not be usable with other Web servers.
1	`crypt` - The default on all platforms but Windows, Netware and TPF. Though possibly supported by htpasswd on all platforms, it is not supported by the httpd server on Windows, Netware and TPF.
2	`SHA-1` - SHA encryption for passwords. Facilitates migration from/to Netscape servers using the LDAP Directory Interchange Format (ldif).

$HtpasswordSortedFile, $HtgroupSortedFile: When set to 1, the password/group file will be kept sorted (by user/group names) between editions (thanks to Petko for the idea).
$HtpasswordMessages: Allow to customize the form feedback outputs (defaults to "(:messages:)").
$HtpasswordTabIndex: Allow to customize the form tabindex start values.
$HtpasswordDefaultGroup: Defines the group in which self registered new users are enrolled (defaults to nothing).
$EnableHtpasswordProfileLinks: When set to 1 (default), usernames are displayed as links to their Profile/… pages (opened in a new page).
$EnableHtpasswordGroupUpdated: When set to 1, the update group(s) checkbox will default to selected.
$HtpasswordGetUserInfo: When set to 1, the new user form would allow definition of the extra user information field (defaults to 0).
$HtpasswordUpdateUserInfo: When set to 1, the user password form would allow to redefine the extra user information field when the password is changed. Use 'clear' to reset field content (defaults to $HtpasswordGetUserInfo).
$HtpasswordRemindUserInfo: When set to 1, the user password form would get an extra Get Comment button to fill the extra user information field (defaults to 0, forces $HtpasswordGetUserInfo to 1).
$HtpasswordMandatory: Prevent usage of blank passwords (defaults to 1 -- PmWiki requirement).
$HtpasswordSimpleNameOnly: Prevent usage of name containing quotes or spaces (defaults to 1 -- PmWiki requirement).

How-to use the recipe as a stand-alone htpasswd/htgroup editor ?

Edit a Local Customizations file, for example local/Admin.MyEditor.php, with the following content:


# Full path to either or both the password/group file(s)
# to administer
$HtpasswdFile = "$FarmD/local/htpasswd";
$HtgroupFile  = "$FarmD/local/htgroup";

# Inconditionally display the admin form
$HtpasswordAuth = 'read';

# Comment the following line to enable links to
# non-relevant profile pages
$EnableHtpasswordProfileLinks = 0;

# Uncomment to enable handling of blank passwords
#$HtpasswordMandatory = 0;

# Uncomment to enable handling of names containing quotes/spaces
#$HtpasswordSimpleNameOnly= 0;

# Uncomment the following line only if you're not using
# AuthUser authentication.
#unset($AuthUser);

Edit the corresponding Wiki page (Admin.MyEditor ? in the given example) and add the (:htpasswdform:) directive to manage your .htpasswd and .htgroup files,…
…and once again, don't forget to protect the wiki page access according to your needs!

Technical hints

The recipe defines the following actions to handle the different forms:

postadmhtpasswd (admin form)
postusrhtpasswd (user form)
postnewhtpasswd (new user form)

Contributors

Dfaure

History

2008-07-28: Enabled user info field edition while changing password. Added user info reminder feature.
2008-07-10: Fixed new user form customization handling.
2008-05-30: Rationalized internal authentication handling and reduced PHP notice messages.
2008-03-18: Synced edition of users between password/group files. Added user info field in new user form. Minor internal fixes.
2007-10-12: Changed blank password handling.
2007-09-18: Improved XHTML validation. Enclosed forms into divs.
2007-07-03: Added Captcha support. Added error messages.
2007-03-21: Added links to user Profile pages. Minor internal fixes.
2007-01-22: Fixed include_once spec.
2007-01-15: Enabled Site.AuthUser password/group file specifications support.
2007-01-04: Minor internal fixes.
2006-10-28: Fixed user renaming bug.
2006-10-25: Added RecipeInfo data.
2006-10-16: Fixed potential security flaws.
2006-10-13: Fixed bugs. Merged group and user handling. Rationalized form tabindex navigation.
2006-10-09: Added group support.
2006-09-25: Added SHA support.
2006-09-06: Merged back publicly unreleased features.
2006-01-24: Added user password change.
2005-09-26: Initial release.

Comments

There does not appear to be an error message when a user types an incorrect 'old' password. Can this be added? -- Allister.

This is a feature. See the password changer form note. --Dfaure

It seems any user can create the password form by just including (:htpasswdform:) in any page. If any user can get access to the password form, what's the point of adding security to my password form page? How can we prevent users from making their own password form page? -- Sean, Sep 2006

You should both take care of narrowing the recipe (wiki page) scope, avoiding using local/config.php and adding include_once("cookbook/htpasswdform.php"); only in local/Site.HtpasswdForm.php (for example), and set the desired page permissions (browsing [[Site.HtpasswdForm?action=attr]]).

I've tried following the above steps and all I get is (:htpasswdform:) in my page - what am I missing? (I set the following variables before the include_once call in the local page customization file: $EnableHtpassword, $HtpasswdFile and $HtpasswordDefaultType)

Before all you should make sure that your customization file is related to the page (name) you're working with ('local/Test.MyPasswdEditor.php' file for 'Test.MyPasswdEditor' page for example). Further details are available here. --Dfaure

Also check your local or farm config.php files to make sure that you haven't inadvertently included htpasswdform.php there - that can also cause problems. shi

Basically, i want to be able to give someone an initial password, but force them to change it on first login. Is it possible to flag something in a php recipe that would force the user to change their password after logging in? If not, this would be a useful checkbox to have on the admin form. --Lordmundi, 2007-03-23

This behavior is beyond the scope of the recipe --Dfaure July 03, 2007, at 03:50 AM

Our Apache runs on a server with a UTF-8 locale. Adding either a group or a user with accented characters (e.g., �land) results in the following error message: "Fatal error: Allowed memory size of 8388608 bytes exhausted (tried to allocate 1025 bytes) in /var/www/pmwiki/cookbook/htpasswdform.php on line 526". The requested user name gets added about 131 times to the htpasswduser file, each line with a different apr1 crypt. The htpasswdform version is 2007-07-03 and our locale settings mimic these: http://myy.helia.fi/~karte/english_in_finland_on_ubuntu.html --Pervil� 13.7.2007

AFAIK, Apache configuration/directives files are used to be plain acsii text files only (and alas, the htpasswd is one of them)... --Dfaure July 23, 2007, at 05:49 PM

I had more time to debug the problem above. Actually, the htpasswd file's content is written with UTF-8 encoding, correctly (verified with od). Line 529 is the fgets call, and for a moment I suspected rtrim beneath it. It is not the culprit - by changing the memory limit (ini_set("memory_limit"...)) of the htpasswdform script, the error message changes. So something starts to leak memory when UTF-8 is used. I'm not even sure it is htpasswdform anymore. UserAuth2-Talk contains something similar. --Pervil� 29.9.2007

Not sure if it is a bug. Unauthororized user can't create new user account (even the form does show). After I change the 59th line from
if(IsEnabled($HtpasswordNewUsers, 0))
to
if(IsEnabled($HtpasswordNewUsers, 1))
then it's all set... -- Terrence

The "normal" (and future-proof version) way to define a flag is to do it in your local configuration file just before the script reference:

$HtpasswordNewUsers = 1;
include_once("$FarmD/cookbook/htpasswdform.php");

--Dfaure August 31, 2007, at 06:51 AM

passwords don't match.
line 447
if($plain != $_REQUEST['passwd2']) {
change to
if(!$plain or $plain != $_REQUEST['passwd2']){

Technically speaking, Apache and the related tools are able to handle blank passwords but since PmWiki prohibits them the default behavior has been changed (you should now set explicitely $HtpasswordMandatory = 0; to allow blank passwords). --Dfaure October 12, 2007, at 08:51 AM

Is it possible to expand the recipe, that new users (i have set HtpasswordNewUsers to 1) have to provide their email-address in the comment field when they are registering themselves? schroe ? January 28, 2008

Available in last release. --Dfaure March 18, 2008, at 09:54 AM

Is there a way to expand more required options to be included in new-user registration such as telephone number, address, etc.? If so, how do I do that? Thanks, Chris 8-26-08

This would require a large rewriting of the recipe, which is not really planned for now. --Dfaure August 26, 2008, at 07:12 AM

Thanks for your quick response! I'm in a time crunch and therefore, although the news isn't positive, am benefitting from your timeliness. ;-) Ok, so, is there a way that I could have a new user register via this recipe, but then require them to have their accounts on hold until I approve it to when I receive all the information from them? Practically, I have a new user register giving their username, password, e-mail address and then have their account on hold until I approve it (by requiring them to send me an e-mail with the required information such as home phone, address, etc.?) Thanks, Chris 8-26-08

Like an above user, I followed the directions at the top of the page (using the example filenames, etc.), but when I visit the page, I get a page-not-found error: "The page "Site.HtpasswdForm" doesn't exist." local/Site.HtpasswdForm.php contains only "include_once("$FarmD/cookbook/htpasswdform.php");", the htpasswdform.php is in the /cookbook directory. --Xax ? March 15, 2008

You must also create a Site.HtpasswdForm page containg the (:htpassword:) directive. --Dfaure March 16, 2008, at 05:18 AM

forceflow Could you add the functionality for regular users to update their 'comment' field too ? Very useful if you store e-mail adresses there.

Implemented in latest release. --Dfaure July 28, 2008, at 05:18 PM

Could you please explain how to use $HtpasswordForms to customise the forms (especially the user-registration form)? (I really like this recipe, by the way; it's fantastic to be able to use the same users and groups elsewhere!) Sam Wilson May 29, 2008, at 08:48 PM

The $HtpasswordForms forms are made of regular markup texts in which some tokens/placeholders are replaced to a computed definition:

$HtpasswordForms['user']: The user password change markup code in which the $UserName token will be replaced by the name of the currently authenticated user (333).
$HtpasswordForms['new']: The new user registration form (388), handling the $UserInfo and $Captcha tokens as place holders for the next sub-form optional elements:
$HtpasswordForms['info']: The user comment field (395).
$HtpasswordForms['captcha']: The captcha field (402).

(bracketed numbers refer to the source code lines where each variable is defined. --Dfaure May 30, 2008, at 05:10 AM

In my setup there are various groups, each with his set of moderators (elsewhere decided by membership in @groupmoderator). What I need is that a moderator should be able to add users to *his group* (add, delete new users). What changes should I make?

This feature is not planned for now. --Dfaure July 28, 2008, at 05:18 PM

Is there a password reminder/reset feature? Sam Wilson July 16, 2008, at 01:37 AM

Implemented in latest release using the user comment field. --Dfaure July 28, 2008, at 05:18 PM

HtpasswdForm