Manage Users

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

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

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 NewUserTemplate and 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 Main web, such as from JaneSmith to JaneMiller.
  • Fix backlinks in the Main web only
  • Make sure the group topics are updated (if any.)
• Edit the 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:
  

  %M% Jane Smith is now known as JaneMiller

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 WikiUsers topic, fix the mapping from login name to WikiName:
     * JaneSmith - jsmith - 13 Sep 2006
  to:
     * JaneMiller - jmiller - 13 Sep 2006

Removing User Accounts

To remove a user account (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 Main.WikiUsers topic
3. Remove FredQuimby from all groups and from all the ALLOWWEB/ALLOWTOPIC... declarations, if any.
   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.
4. [optional] Delete their user topic Main.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 UserName topic should also prevent that user name from being re-used, sealing the potential security hole regarding inherited permissions..

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:

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:

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

Note the use of %WIKINAME%, %FIRSTLASTNAME%, %EMAILADDRESS% passed in from the INCLUDE so that the topic below is similar to the original template

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

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%

Remember to secure the topic appropriately to prevent attackers from getting emailed sensitive passwords.

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 SitePreferences topic and enable the new skin, and set the %REGISTRATIONAPPROVAL% and %REGISTRATIONAPPROVALEMAIL% variables
7. Enable confirmation email messages using https://nkwiki.de/foswiki/bin/configure to enable {Register}{NeedVerification}

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

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.

%{ 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%

Note The line following the Content-Transfer must be completely empty, with no spaces, or the email wil fail.

Registration response message templates/messages.approval.tmpl

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.

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%

Wiki Admin notification templates/registernotifyadmin.approval.tmpl

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

%{ 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%

Site preferences Main.SitePreferences

Edit your SitePreferences topic and enable the new skin, and set the %REGISTRATIONAPPROVAL% and %REGISTRATIONAPPROVALEMAIL% variables. (Do not include the # shown in the below example.)

   * #Set SKIN=approval,pattern
   * #Set REGISTRATIONAPPROVAL=Registraions
   * #Set REGISTRATIONAPPROVALEMAIL=registrations@mycompany.com

Note Be sure to add the REGISTRATIONAPPROVAL and REGISTRATIONAPPROVALEMAIL to the Set FINALPREFERENCES line.

---

Related Topics: AdminDocumentationCategory