%META:TOPICINFO{author="HaraldJoerg" date="1134513859" format="1.1" version="1.3"}%
%META:TOPICPARENT{name="WebHome"}%
---+ Install Password Add-On

This add-on allows TWiki users who have forgotten their password and who do not have a valid e-mail address in their personal home topic to ask the TWiki administration to install a new one.  The TWiki administration is seeing the password in encrypted form only, so there is no need for the user to change it immediately after the installation.

The add-on is intended for TWikis with a very large number of registered users who write rarely, so that outdated mail addresses and forgotten passwords create too much work for the administrator.  http://twiki.org/ seems to be a well known example for this type of TWiki.

The add-on works only for password managements which respect =$TWiki::cfg{Htpasswd}{Encoding}= and support the value 'plain'.
=$TWiki::cfg{PasswordManager} = 'TWiki::Users::HtPasswdUser'= is ok, but neither =TWiki::Users::ApacheHtPasswdUser= nor any more sophisticated password management (LDAP etc) will work.

---++ Usage

   * A user fills the form at !TWiki.InstallPassword and submits it.  The form has the following field:
      * The User's login name
      * The password to be installed
         * A second text field for a confirmation of this password
      * The user's mail address
      * A comment field which allows the user to prove that he is the owner of the login name, enter a phone number for callback, or whatever seems appropriate.
   * If the configuration variable =$TWiki::cfg{Register}{NeedVerification}= is set, the user must confirm the password installation by submitting another form with a key parameter he gets sent to his email address.
   * The TWiki administrator (as defined in this plugin's settings) receives a mail containing a link which enables him to install the password, after having convinced himself that the request is justified. The password in this mail is encrypted according to TWiki's rules.


---++ Add-On Installation Instructions

__Note:__ You do not need to install anything on the browser to use this add-on. The following instructions are for the administrator who installs the add-on on the server where TWiki is running. 

   * Download the ZIP file from the Add-on Home (see below)
   * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
     | ==data/TWiki/%TOPIC%.txt== | Add-on topic |
     | ==data/TWiki/%TOPIC%.txt,v== | Add-on topic repository |
     | ==data/TWiki/InstallPassword.txt== | User form to request password installation |
     | ==data/TWiki/InstallPassword.txt,v== | User form repository |
     | ==bin/installpassword== | Add-on script |
     | ==lib/TWiki/UI/InstallPassword.pm== | Support module containing most of the code |
     | ==templates/mailinstallpasswordapprove.tmpl== | Template for mail to admin to inform about user's request |
     | ==templates/mailinstallpassworddone.tmpl== | Template for mail to user to inform about the success |
     | ==templates/mailinstallpasswordapprove.tmpl== | Template for mail to user containing verification code |
     | ==templates/oopsinstallpasswordapprove.tmpl== | Template to ask the user to wait for approval |
     | ==templates/oopsinstallpassworddone.tmpl== | Template to inform the admin about success or failure |
     | ==templates/oopsinstallpasswordverify.tmpl== | Template to read user's verification code |

   * Test if the installation was successful:  The valiant can simply install his own password for his own login name, but a cautious user would create a test object:
      1 [[TWiki.TWikiRegistration][Register]] a dummy user with Wikiname e.g. !InstallPasswordUser.
      2 Visit TWiki.InstallPassword and fill in the fields.  You can supply your own e-mail address for this test.  Submit, and have a look at the form you get as a response.
      3 If =$TWiki::cfg{Register}{NeedVerification}= has a true value, you will receive a mail asking for confirmation.  Visit the link given, or enter the verification code to the form from the previous step.
      4 The adminstrator will now receive a mail informing about !InstallPasswordUser's request to install a new password.  The mail contains a link he can simply click on.
         * The mail contains a warning that the administrator has to validate _somehow_ that the person making the request is the valid !InstallPasswordUser.
      5 On successful operation, the user receives a mail which informs about the successful installation.
   * Note that there's no hint in TWiki.ChangePassword or TWiki.ResetPassword whether this addon has been installed.  You might want to drop a note in your TWiki if you have this addon installed.


---++ Add-On Info

|  Add-on Author: | TWiki:Main/HaraldJoerg |
|  Add-on Version: | 01 Dec 2005 (v1.000) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  01 Dec 2005: | Initial version |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  License: | GPL |
|  Add-on Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topic:__ %TWIKIWEB%.TWikiAddOns

-- TWiki:Main/HaraldJoerg - 01 Dec 2005