TWiki/ManagingUsers.mdwn

   1 # <a name="Manage Users"></a> Manage Users
   2
   3 _Register users on your TWiki site; change/reset/install passwords; remove user accounts_
   4
   5 <div>
   6   <ul>
   7     <li><a href="#Manage Users"> Manage Users</a><ul>
   8         <li><a href="#Authentication and Access Contro"> Authentication and Access Control</a></li>
   9         <li><a href="#Register User"> Register User</a></li>
  10         <li><a href="#Change, Reset and Install Passwo"> Change, Reset and Install Passwords</a></li>
  11         <li><a href="#Changing User Account Names"> Changing User Account Names</a></li>
  12         <li><a href="#Removing User Accounts"> Removing User Accounts</a></li>
  13         <li><a href="#Customizing registration Emails."> Customizing registration Emails.</a></li>
  14       </ul>
  15     </li>
  16   </ul>
  17 </div>
  18
  19 %X% Some of the features below may be disabled, depending on your TWiki configuration.
  20
  21 ## <a name="Authentication and Access Contro"></a> Authentication and Access Control
  22
  23 - [[TWikiUserAuthentication]] describes your options for user authentication
  24 - [[TWikiAccessControl]] describes how to define groups and how to restrict access to content
  25
  26 ## <a name="Register User"></a> Register User
  27
  28 You don't have to have user home pages in TWiki for Authentication to work - see [[TWikiUserAuthentication]] for details.
  29
  30 - [[TWikiRegistration]] is used when you want new users to individually register with TWiki by filling out a form
  31 - You can create a custom versions of [[NewUserTemplate]] and [[UserForm]]
  32 - [[BulkRegistration]] is used by administrators to register multiple users at the same time
  33
  34 ## <a name="Change, Reset and Install Passwo"></a> Change, Reset and Install Passwords
  35
  36 _Note that the below features are only relevant when you use an internal password manager where TWiki can set and reset passwords._
  37
  38 - [[ChangePassword]] is for users who _can_ remember their password and want to change it
  39 - [[ResetPassword]] is for users who _cannot_ remember their password; a system generated password is e-mailed to them
  40 - [[BulkResetPassword]] if for administrators who want to reset many passwords at once
  41 - [[ChangeEmailAddress]] changes the hidden email address stored in the password file
  42
  43 ## <a name="Changing User Account Names"></a> Changing User Account Names
  44
  45 To change the user's [[WikiName]]:
  46
  47 - Rename the user's TWiki homepage in the Main web, such as from `JaneSmith` to `JaneMiller`.
  48   - Fix backlinks in the Main web only
  49   - Make sure the group topics are updated (if any.)
  50 - Edit the [[Main.TWikiUsers|Main/TWikiUsers]] topic and move the user's entry so that the list is in proper alphabetical order.
  51 - Recreate the old topic with a pointer to the new topic, so that links in other webs work properly. Example content:%BR% `%M% Jane Smith is now known as JaneMiller`
  52
  53 If external authentication is used and you want to change the login name:
  54
  55 - The login name needs to be changed in the authentication server (e.g. Active Directory)
  56 - In TWiki's [[Main.TWikiUsers|Main/TWikiUsers]] topic, fix the mapping from login name to [[WikiName]]:%BR% `   * JaneSmith - jsmith - 13 Sep 2006` %BR% to: %BR% `   * JaneMiller - jmiller - 13 Sep 2006`
  57
  58 ## <a name="Removing User Accounts"></a> Removing User Accounts
  59
  60 To remove a user account (FredQuimby, who logs in as "fred"):
  61
  62 1. If you are using a `.htpasswd` file, edit the `.htpasswd` file to delete the line starting `fred:`
  63   - **Warning:** Do **not** use the Apache `htpasswd` program with `.htpasswd` files generated by TWiki! `htpasswd` wipes out email addresses that TWiki plants in the info fields of this file.
  64 2. Remove the `FredQuimby - fred` line from the Main.TWikiUsers topic
  65 3. Remove `FredQuimby` from all groups and from all the `ALLOWWEB/ALLOWTOPIC...` declarations, if any.%BR% **_Note:_** If you fail to do this you risk creating a security hole, as the next user to register with the wikiname FredQuimby will inherit the old FredQuimby's permissions.
  66 4. _[optional]_ Delete their user topic Main.FredQuimby (including attachments, if any.)
  67
  68 **_Note:_** Consider leaving the user topic file in place so their past signatures and revision author entries don't end up looking like [[AnUncreatedTopic]]. If you want to make it clear the user is no longer around, replace the topic content with a note to that effect. The existence of the UserName topic should also prevent that user name from being re-used, sealing the potential security hole regarding inherited permissions..
  69
  70 ## <a name="Customizing registration Emails."></a> Customizing registration Emails.
  71
  72 TWiki's Registration can send 3 emails who's output is governed by templates:
  73
  74 1. User registration confirmation - `templates/registerconfirm.tmpl`
  75 2. User registration notification - `templates/registernotify.tmpl`
  76 3. Email to notify the TWiki admin of registration - `templates/registernotifyadmin.tmpl`
  77
  78 As these are [[TWikiTemplates]], they can be customized and selected using the SKIN path setting. Because there are default tmpl files in the `templates` dir, this cannot use Template topics.
  79
  80 These template files have a specific format that matches the raw format of emails sent via SMTP, so be careful and test your changes. It is easiest to start by copying the default templates:
  81
  82     cd twiki/templates
  83     cp registernotify.tmpl registernotify.myskin.tmpl
  84     cp registerconfirm.tmpl registerconfirm.myskin.tmpl
  85     cp registernotifyadmin.tmpl registernotifyadmin.myskin.tmpl
  86
  87 then add `myskin` to the beginning of the `SKIN` setting in [[TWikiPreferences]].
  88
  89 From this point on, your myskin templates will be used for the registration emails.
  90
  91 To make it possible for [[TWikiUsers]] to modify the email contents, you could use a parameterized `%INCLUDE%` statement in your customized version. eg:
  92
  93     From: %WIKIWEBMASTERNAME% <%WIKIWEBMASTER%>
  94     To: %FIRSTLASTNAME% <%EMAILADDRESS%>
  95     Subject: %MAKETEXT{"[_1] - Registration for [_2] ([_3])" args="%WIKITOOLNAME%, %WIKINAME%, %EMAILADDRESS%"}%
  96     MIME-Version: 1.0
  97     Content-Type: text/plain; charset=%CHARSET%
  98     Content-Transfer-Encoding: 8bit
  99
 100     %INCLUDE{
 101         "Main.RegistrationNotification"
 102         WIKINAME="%WIKINAME%"
 103         FIRSTLASTNAME="%FIRSTLASTNAME%"
 104         EMAILADDRESS="%EMAILADDRESS%"
 105     }%
 106
 107 - **_note the use of %WIKINAME%, %FIRSTLASTNAME%, %EMAILADDRESS% passed in from the INCLUDE so that the topic below is similar to the original template_**
 108
 109 and then create a topic Main.RegisterNotifyEmail:
 110
 111     Welcome to %WIKITOOLNAME%.
 112
 113     %MAKETEXT{"Your personal [_1] topic is located at [_2]. You can customize it as you like:" args="%WIKITOOLNAME%, %SCRIPTURL{"view"}%/%USERSWEB%/%WIKINAME%"}%
 114
 115        * %MAKETEXT{"Some people turn it into a personal portal with favorite links, what they work on, what help they'd like, etc."}%
 116        * %MAKETEXT{"Some add schedule information and vacation notice."}%
 117
 118     Regards
 119     %WIKIWEBMASTERNAME%
 120     Your TWiki Admin
 121
 122     %MAKETEXT{"Note:"}%
 123        2 %MAKETEXT{"You can change your password at via [_1]" args="%SCRIPTURL{"view"}%/%SYSTEMWEB%/ChangePassword"}%
 124        3 %MAKETEXT{"If you haven't set a password yet or you want to reset it, go to: [_1]" args="%SCRIPTURL{"view"}%/%SYSTEMWEB%/ResetPassword"}%
 125
 126     %MAKETEXT{"Submitted content:"}%
 127     %FORMDATA%
 128
 129 - **_remember to secure the topic appropriately to prevent attackers from getting emailed sensitive passwords._**
 130
 131 **_Related Topics:_** [[AdminDocumentationCategory]]