Manage Users

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

On this page:

ALERT! Some of the features below may be disabled, depending on your Foswiki configuration.

Authentication and Access Control

Register User

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

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.

Changing User Account Names

To change the user's WikiName:

If external authentication is used and you want to change the login username:

Removing User Accounts

The following form can be used by administrators to delete a user's account:

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 username from being re-used, sealing the potential security hole regarding inherited permissions.

Enter user to be removed

Remove user topic?

(Check to remove topic) Prefix for deleted topic: (Follow topic naming rules)

TIP For Foswiki versions prior to Foswiki 2.0, see the AntiWikiSpamPlugin extension for another method of removing users. It provides a rest handler to:

Configuring User Registration

The registration process is configured at configure Security and Authentication tab, Registration sub-tab.

Verification of the new registration email address

Registration can be configured to require a verification via the registered email address: {Register}{NeedVerification}

Administrative approval of new registrations

Registration can be configured to require approval. {Register}{NeedApproval}

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 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/ 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 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 Main 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:

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

Using these two steps, you can:

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 NewUserTemplate and UserForm

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

  1. Copy System.NewUserTemplate to Main.NewUserTemplate
  2. Modify the page as desired.

The Registration process will automatically find and use the Main 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 System.NewUserTemplate to Main.UserTemplate
  2. Copy System.UserForm to Main.UserForm
  3. Make your desired changes.
  4. Edit System.NewUserTemplate, delete the UserForm, and add your new Main form.
See System.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:

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).

cd templates
cp registernotify.tmpl registernotify.myskin.tmpl
cp registerconfirm.tmpl registerconfirm.myskin.tmpl
cp registernotifyadmin.tmpl registernotifyadmin.myskin.tmpl
then add myskin to the beginning of the SKIN setting in 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 %INCLUDE% statement in your customized version, eg:

Subject: %MAKETEXT{
   "[_1] - Registration for [_2] ([_3])"
Auto-Submitted: auto-generated
MIME-Version: 1.0
Content-Type: text/plain; charset=%CHARSET%
Content-Transfer-Encoding: 8bit

HELP Note the use of %WIKINAME%, %FIRSTLASTNAME%, %EMAILADDRESS%, passed in from the INCLUDE so that the topic below is similar to the original template. The %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.

and then create a topic Main.RegisterNotifyEmail:
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."}%

Your Wiki Admin

   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:"}%

Related Topics: AdminDocumentationCategory