ManagingUsers < System < BACCHUS Wiki

You are here: BACCHUS Wiki>System Web>ReferenceManual>ManagingUsers (revision 1) (raw view)
%STARTINCLUDE%
---+ Manage Users

_Register users on your Foswiki site; change/reset/install passwords; remove user accounts_

%TOC%

<blockquote class="foswikiHelp"> %X% Some of the features below may be disabled, depending on your Foswiki
configuration.</blockquote>

---++ Authentication and Access Control

   * UserAuthentication describes your options for user authentication
   * AccessControl describes how to define groups and how to restrict
     access to content

---++ Register User

You don't have to have user home pages in Foswiki for Authentication to
work - see UserAuthentication for details.

   * UserRegistration is used when you want new users to individually
     register with Foswiki by filling out a form
   * You can create a custom versions of %SYSTEMWEB%.NewUserTemplate and
     %SYSTEMWEB%.UserForm
   * BulkRegistration is used by administrators to register multiple users at
     the same time

---++ Change, Reset and Install Passwords

_Note that the below features are only relevant when you use an internal password manager where Foswiki can set and reset passwords._

   * ChangePassword is for users who _can_ remember their password and want to
     change it
   * ResetPassword is for users who _cannot_ remember their password; a system
     generated password is e-mailed to them
   * BulkResetPassword is for administrators who want to reset many passwords
     at once
   * ChangeEmailAddress changes the hidden email address stored in the password
     file

---++ Changing User Account Names

To change the user's WikiName:
   * Rename the user's Foswiki homepage in the %USERSWEB% web, such as
     from =JaneSmith= to =JaneMiller=.
      * Fix backlinks in the %USERSWEB% web only
      * Make sure the group topics are updated (if any.)
   * Edit the [[%USERSWEB%.WikiUsers]] topic and move the user's entry so
     that the list is in proper alphabetical order.
   * Recreate the old topic with a pointer to the new topic, so that links
     in other webs work properly. Example content:%BR%
     <verbatim class="tml">%M% Jane Smith is now known as JaneMiller</verbatim>

If external authentication is used and you want to change the login name:
   * The login name needs to be changed in the authentication server (e.g.
     Active Directory)
   * In Foswiki's [[%USERSWEB%.WikiUsers]] topic, fix the mapping from
     login name to WikiName:%BR%
     =&nbsp;  * !JaneSmith - jsmith - 13 Sep 2006= %BR%
     to: %BR%
     =&nbsp;  * !JaneMiller - jmiller - 13 Sep 2006=

---++ Removing User Accounts

To remove a user account (<nop>FredQuimby, who logs in as "fred"):

   1 If you are using a =.htpasswd= file, edit the =.htpasswd= file to
     delete the line starting =fred:=
      * *Warning:* Do *not* use the Apache =htpasswd= program with
        =.htpasswd= files generated by Foswiki! =htpasswd= wipes out email
        addresses that Foswiki plants in the info fields of this file.
   2 Remove the =FredQuimby - fred= line from the <nop>%USERSWEB%.WikiUsers
     topic
   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 Fred<nop>Quimby will inherit the old
      Fred<nop>Quimby's permissions.
   4 _[optional]_ Delete their user topic %USERSWEB%.<nop>FredQuimby
     (including attachments, if any.)

*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 <nop>UserName topic should also prevent that user name from being re-used, sealing the potential security hole regarding inherited permissions..

<div class="foswikiHelp">
%T% See the [[http://foswiki.org/Extensions/AntiWikiSpamPlugin][AntiWikiSpamPlugin]] extension for another method of removing users.  It provides a =rest= handler to:
   * Move the user topic to the Trash web.
   * Remove the user from the password / mapper
   * Remove the user from any groups.
</div>

---++ Other registration controls

Registration process is configured at %SCRIPTURL{"configure"}%#Registration$SecurityAndAuthentication

---+++ Confirmation

Registration can be configured to require a confirmation via the registered email address:
   * An email is sent to the email address entered by the new user with a confirmation code.
   * The user must enter the confirmation code into a dialog on the wiki to confirm the registration.
   * The pending registration lifetime defaults to 6 hours.  If the user does not confirm within that time, the pending registration will be removed.

---+++ Registration Email Requirements

Normally Foswiki does not require unique email addresses. Multiple users can register using the same email address.   Enable the setting ={Register}{UniqueEmail}=  to prevent use of the same email by multiple users.

Normally any email domain can be used for registration.  Set the _expert_ setting ={Register}{EmailFilter}= to restrict the domains usable for registration.  See the configure help for more details.

See the configure help at %SCRIPTURL{"configure"}%#Registration$SecurityAndAuthentication for more details.

---++ Customizing registration Emails.
Foswiki's Registration can send 3 emails whose output is governed by templates:
   1 User registration confirmation - =templates/registerconfirm.tmpl=
   2 User registration notification - =templates/registernotify.tmpl=
   3 Email to notify the Wiki admin of registration - =templates/registernotifyadmin.tmpl=

As these are SkinTemplates, 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.

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:

<verbatim class="bash">
cd templates
cp registernotify.tmpl registernotify.myskin.tmpl
cp registerconfirm.tmpl registerconfirm.myskin.tmpl
cp registernotifyadmin.tmpl registernotifyadmin.myskin.tmpl
</verbatim>
then add =myskin= to the beginning of the =SKIN= setting in %USERSWEB%.SitePreferences.

From this point on, your myskin templates will be used for the registration emails.

To make it possible for users to modify the email contents, you could use a parameterized =%<nop>INCLUDE%=
statement in your customized version, eg:

<verbatim class="tml">
From: %WIKIWEBMASTERNAME% <%WIKIWEBMASTER%>
To: %FIRSTLASTNAME% <%EMAILADDRESS%>
Subject: %MAKETEXT{
   "[_1] - Registration for [_2] ([_3])"
   args="%WIKITOOLNAME%, %WIKINAME%, %EMAILADDRESS%"
}%
MIME-Version: 1.0
Content-Type: text/plain; charset=%CHARSET%
Content-Transfer-Encoding: 8bit

%INCLUDE{
    "%USERSWEB%.RegisterNotifyEmail"
    WIKINAME="%WIKINAME%"
    FIRSTLASTNAME="%FIRSTLASTNAME%"
    EMAILADDRESS="%EMAILADDRESS%"
}%
</verbatim>
<blockquote class="foswikiHelp"> %H% *Note* the use of %<nop>WIKINAME%, %<nop>FIRSTLASTNAME%, %<nop>EMAILADDRESS% passed in from the INCLUDE so that the topic below is similar to the original template</blockquote>

and then create a topic %NOP%%USERSWEB%.RegisterNotifyEmail:
<verbatim class="tml">
Welcome to %WIKITOOLNAME%.

%MAKETEXT{"Your personal [_1] topic is located at [_2]. You can customize it as you like:" args="%WIKITOOLNAME%, %SCRIPTURL{"view"}%/%USERSWEB%/%WIKINAME%"}%

   * %MAKETEXT{"Some people turn it into a personal portal with favorite links, what they work on, what help they'd like, etc."}%
   * %MAKETEXT{"Some add schedule information and vacation notice."}%

Regards
%WIKIWEBMASTERNAME%
Your Wiki Admin


%MAKETEXT{"Note:"}%
   2 %MAKETEXT{"You can change your password at via [_1]" args="%SCRIPTURL{"view"}%/%SYSTEMWEB%/ChangePassword"}%
   3 %MAKETEXT{"If you haven't set a password yet or you want to reset it, go to: [_1]" args="%SCRIPTURL{"view"}%/%SYSTEMWEB%/ResetPassword"}%

%MAKETEXT{"Submitted content:"}%
%FORMDATA%

</verbatim>
<blockquote class="foswikiHelp">%X% *Remember* to secure the topic appropriately to prevent attackers from getting emailed sensitive passwords.</blockquote>

---++ Manually approving registrations
In some installations, registration requests should be forwarded to an administrator for approval.  This can be accomplished relatively easily by
modifying the registration email template to send the "Verification" request to an approval address instead of returning to the user.

This will be accomplished by creating a new skin to override the templates used in the registration process.  By creating a new skin, you avoid modifying
any files that are replaced when Foswiki is upgraded.

---+++!! Summary of steps:
   1 Name a new skin for the registration email:  ex. =approval=
   2 Copy and modify the registration confirmation - =templates/registerconfirm.tmpl= to =templates/registerconfirm.approval.tmpl=
   3 _optional_ Copy and modify the registration notification - =templates/registernotify.tmpl= to =templates/registernotify.approval.tmpl=
   4 _optional_ Copy and modify the the Wiki admin notification - =templates/registernotifyadmin.tmpl= to =templates/registernotifyadmin.approval.tmpl=
   5 Create a new template to override the registration response to the user:  =templates/messages.approval.tmpl=
   6 Edit your [[%LOCALSITEPREFS%]] topic and enable the new skin, and set the %<nop>REGISTRATIONAPPROVAL% and %<nop>REGISTRATIONAPPROVALEMAIL% variables
   7 Enable confirmation email messages using %SCRIPTURL{"configure"}%#Registration$SecurityAndAuthentication to enable ={Register}{NeedVerification}=
   8 Also, set the ={Register}{ExpireAfter}= setting to a value long enough to ensure that the approver has a chance to process the request before it expires.

The following examples assume that Step 1 chose =approval= as the skin name.  And the registration notifications sent to the user and Wiki admin do not need to be modified.

---+++!! Registration confirmation template =templates/registerconfirm.approval.tmpl= _(Step 2)_

Copy the template:  =cp templates/registerconfirm.tmpl templates/registerconfirm.approval.tmpl= and edit to appear as follows.
This email message will be sent to the address responsible for approving registrations.

<verbatim class="tml">
%{ This is a default template }%From: %WIKIWEBMASTERNAME% <%WIKIWEBMASTER%>
To: %REGISTRATIONAPPROVAL% <%REGISTRATIONAPPROVALEMAIL%>
CC: %WIKIWEBMASTERNAME% <%WIKIWEBMASTER%>
Subject: Registration request by %FIRSTLASTNAME% <%EMAILADDRESS%>
MIME-Version: 1.0
Content-Type: text/plain; charset=%CHARSET%
Content-Transfer-Encoding: 8bit

Registration request by %FIRSTLASTNAME% <%EMAILADDRESS%> for %WIKITOOLNAME%
needs your approval.
Verification code %VERIFICATIONCODE%

%SCRIPTURL{"register"}%?action=verify;code=%VERIFICATIONCODE%
</verbatim>
<blockquote class="foswikiHelp"> %T% *Note* The line following the =Content-Transfer= *must* be completely empty, with no spaces, or the email wil fail.</blockquote>

---+++!! Wiki Admin notification =templates/registernotifyadmin.approval.tmpl= _(Step 4)_

This is sent to the Admin upon successful registration.  This message is
extended to provide confirmation to the approver that the registration
succeeded.

<verbatim class="tml">
%{ This is a default template }%From: %WIKIWEBMASTERNAME% <%WIKIWEBMASTER%>
To: %WIKIWEBMASTERNAME% <%WIKIWEBMASTER%>
Cc: %REGISTRATIONAPPROVAL% <%REGISTRATIONAPPROVALEMAIL%>
Subject: %MAKETEXT{"[_1] - Registration for [_2] ([_3])" args="%WIKITOOLNAME%, %WIKINAME%, %EMAILADDRESS%"}%

MIME-Version: 1.0
Content-Type: text/plain; charset=%CHARSET%
Content-Transfer-Encoding: 8bit

%MAKETEXT{"This is an automated e-mail notification of user registration in [_1]." args="%WIKITOOLNAME%"}%

%MAKETEXT{"[_1] has been approved and registered with e-mail [_2]" args="%WIKINAME%, %EMAILADDRESS%"}%

%MAKETEXT{"Submitted content:"}%

%FORMDATA%

%MAKETEXT{"Saved to:"}%

%SCRIPTURL{"view"}%/%USERSWEB%/%WIKINAME%
</verbatim>

---+++!! Registration response message =templates/messages.approval.tmpl= _(Step 5)_

Create a new template: =templates/messages.approval.tmpl= This template will
override one message from the large collection of messages in =templates/messages.tmpl=

This ="confirm"= message will be returned to the user when they submit the registration request.

<verbatim class="tml">
%TMPL:INCLUDE{"messages"}%
%TMPL:DEF{"confirm"}%
---+++ %MAKETEXT{"Thank you for registering"}%

Your request has been sent to %REGISTRATIONAPPROVAL% <%REGISTRATIONAPPROVALEMAIL%> who will normally approve your
registration within 1-2 working days.

Return to %USERSWEB%.%HOMETOPIC%
%TMPL:END%
</verbatim>

---+++!! Site preferences =%LOCALSITEPREFS%= _(Step 6)_

Edit your [[%LOCALSITEPREFS%]] topic and enable the new skin, and set the %<nop>REGISTRATIONAPPROVAL% and %<nop>REGISTRATIONAPPROVALEMAIL% variables.  (Do not include the =#= shown in the below example.)
<verbatim class="tml">

   * #Set SKIN=approval,pattern
   * #Set REGISTRATIONAPPROVAL=Registraions
   * #Set REGISTRATIONAPPROVALEMAIL=registrations@mycompany.com
</verbatim>
<blockquote class="foswikiHelp"> %X% *Note* Be sure to add the REGISTRATIONAPPROVAL and REGISTRATIONAPPROVALEMAIL to the =Set FINALPREFERENCES= line.</blockquote>

---+++!! Edit the Registration Configuration _(Steps 7-8)_

<blockquote>
   $ ={Register}{NeedVerification}=: This checkbox should be enabled in the "Security and Authentication" -> "Registration" tab.
   $ ={Register}{ExpireAfter}=: Set to a value that is > than the longest delay expected for approval.  For ex.  a "Holiday weekend" - 3-day lifetime would require 259200 seconds.
<div class="foswikiHelp">
Set the pending registration timeout, in seconds. The pending registration
will be cleared after this amount of time. The default is 6 hours (21600
seconds). This is only used if {Register}{NeedVerification} is enabled.

Note By default, registration expiry is done "on the fly" during the
registration process. For best performance, you can set
={Register}{ExpireAfter}= to a negative number, which will mean that Foswiki
won't try to clean up expired registrations durning registration. Instead you
should use a cron job to clean up expired sessions. The standard maintenance
cron script =tools/tick_foswiki.pl= includes this function.

Note that if you are using registration approval by 3rd party reviewers, this
timer should most likely be significantly increased. 24 hours = 86400, 3 days
= 259200.

Pending registration requests are stored in the
={WorkingDir}/registration_approvals= directory.
</div>

</blockquote>

---
*Related Topics:* AdminDocumentationCategory
<!-- %JQREQUIRE{"chili"}% -->
Topic revision: r1 - 18 Apr 2011, ProjectContributor
System
Copyright &© by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding BACCHUS Wiki? Send feedback