HtpasswdForm

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

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

  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!

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:

Name:

Old Password:

New Password:

again:

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

non-functional admin sample form:

/pathname/of/your/htgroup
Group Users
admins alice charlie
editors alice bob charlie
    
Group:

User(s):


/pathname/of/your/htpasswd
User Password Comment
alice <encrypted password>
bob <encrypted password>
charlie <encrypted password>
 
Username:

Password:

Comment:

again:

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';
      include_once("$FarmD/scripts/authuser.php");
      
    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).
$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):
SchemeType
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).
$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 ?

  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.
    #unset($AuthUser);
    
    
  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

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

Contributors

Dfaure

History

2020-01-14
Fixed missing array initialization
2019-03-12
Fixed stupid forgetting (again)
2017-07-15
Fixed stupid forgetting
2017-06-19
Made it PHP 7.2 compliant
2014-08-25
Fixed last update
2014-07-03
Made it PHP 5.5 compliant
2008-10-27
Fixed insertion of users in groups. Minor internal fixes.
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

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.