%META:TOPICINFO{author="ProjectContributor" comment="" date="1727168305" format="1.1" version="1"}%
%META:TOPICPARENT{name="AdminDocumentationCategory"}%
%STARTINCLUDE%
---+ Manage Users

Register users on your Foswiki site; change/reset/install passwords; remove user accounts

%TOC%

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

---++ 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
   * 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%.%WIKIUSERSTOPIC%]] 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 username:
   * The login username needs to be changed in the authentication server (e.g.
     Active Directory)
   * In Foswiki's [[%USERSWEB%.%WIKIUSERSTOPIC%]] topic, fix the mapping from
     username to WikiName:%BR%
     =&nbsp;  * !JaneSmith - jsmith - 13 Sep 2006= %BR%
     to: %BR%
     =&nbsp;  * !JaneMiller - jmiller - 13 Sep 2006=

---++ Removing User Accounts

%INCLUDE{"RemoveUser"}%

---++ Configuring User Registration

The registration process is configured at [[%SCRIPTURLPATH{"configure"}%][configure]] =Security and Authentication= tab, =Registration= sub-tab.
   * Registration is enabled with ={Register}{EnableNewUserRegistration}= (This is the default)

---+++ Verification of the new registration email address

Registration can be configured to require a verification via the registered email address: ={Register}{NeedVerification}=
   * 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 requests pending verification can be viewed by visiting the System.PendingRegistrationsReport

---+++ Administrative approval of new registrations

Registration can be configured to require approval. ={Register}{NeedApproval}=
   * If confirmation is enabled, the email address is verified per the steps in the prior paragraph
   * An email is then set to the list of Approvers - ={Register}{Approvers}=
   * The approver can then Approve or Deny the registration by following a link in the email.
   * Registrations awaiting approval can be viewed and approved from the System.PendingRegistrationsReport

---+++ Registration Email Requirements

By default, 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.

By default, 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 [[%SCRIPTURLPATH{"configure"}%][configure]] =Security and Authentication= tab, =Registration= sub-tab, for more details.

---+++ Expiration of pending registrations and approvals

By default, expiration of pending registrations and approvals 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, but are no longer in plain text format.  To view the pending registrations see the new System.PendingRegistrations report.

---++ Customizing the User Registration pages
If you modify any of the topic related to User Registration, you should put the modified versions into the %USERSWEB% web.  This will make it easier to
upgrade to new versions of Foswiki.

---+++ Creating a custom User Registration page
Three topics make up the user registration page:
   * [[%SYSTEMWEB%.UserRegistration]]:  A "shim" landing page which will display the %USERSWEB% web version if it exists, otherwise it displays [[%SYSTEMWEB%.DefaultUserRegistration]] _You should never have to change this page!_
   * [[%SYSTEMWEB%.DefaultUserRegistration]]: The actual registration page.  This is what you copy to [[%USERSWEB%.UserRegistration]] for customization.
   * [[%SYSTEMWEB%.UserRegistrationParts]]: The components that make up the page.  More advanced modifications might also have to copy this topic to the %USERSWEB%.

The actual customization steps are documented in comments internal to [[%SYSTEMWEB%.DefaultUserRegistration]]. The general steps are:
   1 Copy  [[%SYSTEMWEB%.DefaultUserRegistration]] to [[%USERSWEB%.UserRegistration]].  (Use the "More topic actions" option on [[%SYSTEMWEB%.DefaultUserRegistration]])
   2 Edit [[%USERSWEB%.UserRegistration]] that you just created and follow the instructions on that page.

Using these two steps, you can:
   * Enable/disable entry of existing %SYSTEMWEB%.UserForm fields in registration. 
   * Enable automatic group membership during registration.

Note that while it may be interesing to enable fields like !OrganizationURL, Comments, etc. they are often used by registration SPAM-Bots to generate
topics with links.

---+++ Creating a custom %SYSTEMWEB%.NewUserTemplate and %SYSTEMWEB%.UserForm

If you want to modify the contents of the user page that is created during
user registration.

   1 Copy [[%SYSTEMWEB%.NewUserTemplate]] to [[%USERSWEB%.NewUserTemplate]]
   1 Modify the page as desired.

The Registration process will automatically find and use the %USERSWEB%
version of the template if it exists.

If you want to customize the contents of the UserForm, for example, to remove
or add field:
   1 Copy [[%SYSTEMWEB%.NewUserTemplate]] to [[%USERSWEB%.UserTemplate]]
   1 Copy [[%SYSTEMWEB%.UserForm]] to [[%USERSWEB%.UserForm]]
   1 Make your desired changes.
   1 Edit [[%SYSTEMWEB%.NewUserTemplate]], delete the UserForm, and add your new %USERSWEB% form.
See [[%SYSTEMWEB%.UserForm#CustomForm]] for more details.

---+++ Creating multiple categories of users

By combining all the above concepts, it's possible to have multiple categories
of users,  for example "Customers", "Vendors", "Employees", each with a
custom Template topic, a custom User form and a custom Registration form.

Multiple categories of users can be supported by:
   * Creating an alternate version of the %SYSTEMWEB%.DefaultUserRegistration page
   * Creating an alternate version of the %SYSTEMWEB%.NewUserTemplate and %SYSTEMWEB%.UserForm
   * And configuring the new registration page to use the new user template.

---++ Customizing registration Emails.
Foswiki's Registration can send 7 emails whose output is governed by templates:
   | User registration confirmation. (Awaiting email verification). | =templates/registerconfirm.tmpl= |
   | User registration failed notification, cleanup was successful. | =templates/registerfailedremoved.tmpl= |
   | User registration failed notification, cleanup of partial registration also failed. | =templates/registerfailednotremoved.tmpl= |
   | User registration denied notification. | =templates/registerdenied.tmpl= |
   | Approver registration pending notification. | =templates/registerapprove.tmpl= |
   | User notification of sucessful registraiton. | =templates/registernotify.tmpl= |
   | Administrator notification of successful 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.

Note: As of Foswiki 2.1.3, the email =From:= address can be different from the WIKIWEBMASTER address, and is configurable using the =bin/configure= tool.
See the "Expert" ={WikiAgentName}= and ={WikiAgentEmail}= settings on the "Mail" section, "Basic Settings and Autoconfiguration" tab.
If these fields are not set, then the WIKIWEBMASTER setting will be used as the =From:= address.

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 that you
wish to change.:  (You don't need to copy every template).

<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 %LOCALSITEPREFS%.

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: %WIKIAGENTNAME% <%WIKIAGENTEMAIL%>
To: %FIRSTLASTNAME% <%EMAILADDRESS%>
Subject: %MAKETEXT{
   "[_1] - Registration for [_2] ([_3])"
   args="%WIKITOOLNAME%, %WIKINAME%, %EMAILADDRESS%"
}%
Auto-Submitted: auto-generated
MIME-Version: 1.0
Content-Type: text/plain; charset=%CHARSET%
Content-Transfer-Encoding: 8bit

%INCLUDE{
    "%USERSWEB%.RegisterNotifyEmail"
    WIKINAME="%WIKINAME%"
    FIRSTLASTNAME="%FIRSTLASTNAME%"
    EMAILADDRESS="%EMAILADDRESS%"
    TEMPLATETOPIC="%TEMPLATETOPIC%"
}%
</verbatim>
<div 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.
The %<nop>TEMPLATETOPIC% variable is also available.  It could be used as a "section" name in the include, or directly in the email for tailoring messages for specific types of users.</div>

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>

---
*Related Topics:* AdminDocumentationCategory

%META:PREFERENCE{name="ALLOWTOPICCHANGE" title="ALLOWTOPICCHANGE" type="Set" value="AdminUser"}%
%META:PREFERENCE{name="PERMSET_CHANGE" title="PERMSET_CHANGE" type="Local" value="nobody"}%
