Summary: Form based management of users and passwords using .htpasswd/.htgroup files
Version: 2020-01-14
Status: Stable
Prerequisites: pmwiki-2.x
License: MIT
Maintainer: Dfaure
Discussion: HtpasswdForm-Talk


(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?


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


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.


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:


Old Password:

New Password:


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

non-functional admin sample form:

Group Users
admins alice charlie
editors alice bob charlie


User Password Comment
alice <encrypted password>
bob <encrypted password>
charlie <encrypted password>




apr1 crypt SHA-1 update group(s)
  • 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:
    1. the 1st 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';
    2. 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).
Selects the privilege level switch between the two forms (defaults to "admin").
When set to 1, a new user form is provided to unauthenticated users, allowing them to register themselves (defaults to 0).
When set to 0, disables the optional new user form captcha (defaults to 1).
When set to 1, allows new users to be logged in once being registered (defaults to 1).
The page name where newly registered users are redirected automatically (defaults to current page).
An array providing the forms used for password change and new user registration.
Selects the default password encoding scheme (defaults to 0, aka apr1). Usable schemes are (as stated in the Apache documentation):
0apr1 - The MD5 algorithm used by htpasswd is specific to the Apache software; passwords encrypted using it will not be usable with other Web servers.
1crypt - 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.
2SHA-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).
Allow to customize the form feedback outputs (defaults to "(:messages:)").
Allow to customize the form tabindex start values.
Defines the group in which self registered new users are enrolled (defaults to nothing).
When set to 1 (default), usernames are displayed as links to their Profile/… pages (opened in a new page).
When set to 1, the update group(s) checkbox will default to selected.
When set to 1, the new user form would allow definition of the extra user information field (defaults to 0).
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).
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).
Prevent usage of blank passwords (defaults to 1 -- PmWiki requirement).
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 ?

  1. 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.
  2. Edit the corresponding Wiki page (Admin.MyEditor? in the given example) and add the (:htpasswdform:) directive to manage your .htpasswd and .htgroup files,…
  3. …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)

See Also

AuthUser, Local Customizations, Group Customizations, Captcha, AuthUserSignup
AuthGroupFile and AuthUserFile Directives,
htpasswd documentation




Fixed missing array initialization
Fixed stupid forgetting (again)
Fixed stupid forgetting
Made it PHP 7.2 compliant
Fixed last update
Made it PHP 5.5 compliant
Fixed insertion of users in groups. Minor internal fixes.
Enabled user info field edition while changing password. Added user info reminder feature.
Fixed new user form customization handling.
Rationalized internal authentication handling and reduced PHP notice messages.
Synced edition of users between password/group files. Added user info field in new user form. Minor internal fixes.
Changed blank password handling.
Improved XHTML validation. Enclosed forms into divs.
Added Captcha support. Added error messages.
Added links to user Profile pages. Minor internal fixes.
Fixed include_once spec.
Enabled Site.AuthUser password/group file specifications support.
Minor internal fixes.
Fixed user renaming bug.
Added RecipeInfo data.
Fixed potential security flaws.
Fixed bugs. Merged group and user handling. Rationalized form tabindex navigation.
Added group support.
Added SHA support.
Merged back publicly unreleased features.
Added user password change.
Initial release.


See discussion at HtpasswdForm-Talk

User notes +3: 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.