Working documentation for the User Mapping code interface

The development of an OpenIDUserMapping, which does not require the registration of users on the TWiki, has guided the refactoring of the TWiki User system to become much more flexible.

By convention users in TWiki are identified by two names; the login name, which is used for login, and the displayed name, which is used for showing which user edited what and building signatures. The displayed name is also used in TWiki access controls. In the past (before 4.2), TWiki has made some gross (and undocumented) assumptions about the format and usage of both the login name and the displayed name, which has made it a major challenge to integrate external authentication systems.

Since the refactoring, it is now possible to have arbitrary login names (names that are not valid rcs usernames, for example, email addresses or URIs, or Windows domain login names). It is also possible to write an alternative UserMapping that manages a bespoke mapping from login names to displayed names, or to write a UserMapping that has its own custom TemplateLogin user interface.

This document describes the authentication and mapping configurations that are available "out of the box", and goes on to describe how to develop your own user mapper.

Overview

The TWiki authentication system is hidden behind three key interfaces:

• The User Mapping Manager interface provides services for mapping between a 'user identity' as used when talking to an external authentication provider, an internal TWiki canonical user ID, and the displayed name used to identify the user in TWiki.
• The Password Manager interface is a low-level interface to an authentication provider. It provides methods for handling password changes, user creation etc.
• The Login Manager interface publishes methods that are used for handling the login process. For example, an inmplementation will:
  • handle the discussion with an external authentication provider when a user logs in
  • handle any screens that are required to prompt for authentication information

TWiki provides default implementations for each of the three interfaces. These implement login using user ids stored in Apache .htpasswd files, interaction with Apache authentication, and mapping to wikinames for displaying users (wikinames are display names constructed by concatenating the first and last names of the user).

Possible configurations

The following configurations should all work out 'of the box', using the default TWiki implementations of the Login Manager, Password Manager and User Mapping Manager interfaces. These configurations should be familiar to anyone who has configured TWiki in the past, and are selected using the {UserMapping}, {AllowLoginName}, and { to be determined } settings in configure.

Purely anonymous TWiki

• {PasswordManager} is set to none
• {LoginManager} is set to none
• {UserMappingManager} is set to none

TWiki does not record the identity of its users at all. The BaseUserMapping automatically creates a single TWikiAdmin user, using the password used for configure. Users do not login in, and their contributions are recorded as being made by 'TWikiGuest' (or whatever alternative username is selected by the {DefaultUserWikiName} setting in configure).

This configuration can be used in combination with the webserver based authentication to limit access to known users, but TWiki will not record their identities.

No user registration or management by TWiki.

• {PasswordManager} is set to TWiki::Users:: HtPasswdUser
• {LoginManager} is set to TWiki::LoginManager::TemplateLogin or TWiki::LoginManager::ApacheLogin
• {UserMappingManager} is set to TWiki::Users::TWikiUserMapping
• {Register}{EnableNewUserRegistration} is set to false

Authentication uses Template or Apache login, and an externally managed .htpasswd file. All TWiki registration topics are disabled. User Topics are not created by TWiki, but they can be created manually by users if the login (in the htpasswd file) is a valid WikiWord. The externally managed .htpasswd is expected to contain email addresses in the info field of each user entry. There are two ways to use this configuration; Single User Name, and Seperate Login Name and Wiki Name.

• This is the configuration of TWiki's bug tracking system, with {Register}{AllowLoginName} = false.

TWiki manages the User database

• {PasswordManager} is set to TWiki::Users::HtPasswdUser.
• {LoginManager} is set to TWiki::LoginManager::TemplateLogin or TWiki::LoginManager::ApacheLogin. - or HTTPDUserAdminContrib
• {UserMappingManager} is set to TWiki::Users::TWikiUserMapping
• {Register}{EnableNewUserRegistration} is set to true

This configuration uses the built-in TWiki support for all aspects of user management. New users can register, and once registered can change and reset their passwords online. User registrations can be verified, or not. Verification requires working email. Again, Single User Name and Seperate Login Name and Wiki Name modes are available.

• This is the configuration of TWiki.org, with {Register}{AllowLoginName} = false.

the {AllowLoginName} Setting

Single User Name

• {Register}{AllowLoginName} is false

Users login with the same Name as they are known as in TWiki. The %MAIN%.TWikiUsers topic is not used by TWiki, and can be ignored, removed or archived.

This mode is the simplest if you are not integrating TWiki into an existing user management system, and is faster, as it does not have to lookup the 'mapping' from login to WikiName.

Seperate Login Name and Wiki Name

• {Register}{AllowLoginName} is true

This makes it simpler to integrate TWiki into existing user management systems, by 'mapping' a Login Name to the Wiki Name displayed by TWiki.

The management of the entries in TWikiUsers topic will be required to map from login to WikiName, and to confirm the existance of that user. This is done by the registration process for TWiki::Users::TWikiUserMapping so must be done seperatly if you are not using TWikiRegistration.

What you need to know to write your own (post 4.2) UserMapping system

High Level Implementation View.

The User Mapping and Password interfaces are hidden behind the TWiki::Users Class (C2Wiki::FacadePattern). The interfaces are in fact implemented as virtual base classes, which may be subclassed to created new implementations. The different implementations are then selected between using the configure interface.

The TWiki::Users::UserMapping implementations map the login identity into TWiki's user, topic, group and rendering system, and TWiki::LoginManager implementations provide the User interfaces to log in.

TWiki::Users::Password implementations can be used by TWiki::Users::UserMapping implementations to provide pluggable for loginname, password and (sometimes) email stores. (They were written for TWiki::Users::TWikiUserMapping)

Basic user mapping functionality is implemented in the TWiki::Users::BaseUserMapping, which manages the default users (TWikiGuest, TWikiAdmin etc), groups and the TWikiAdmin password automatically - without requiring UserTopics, nor registration.

TWiki::Users::TWikiUserMapping provides the mapping for other users using the traditional of TWikiUser topics, and the TWikiUsers topic. It, or other mappings can be selected via configure.

This approach has made it possible to implement AddTWikiAdminUser's sudo login without creating custom code, or making it much more complex for third parties to implement a user mapping.

TWiki::Users::UserMapping implementations

TWiki::Users::TWikiUserMapping implements "traditional TWiki", and is the only UserMapping implementation shipped by default. It uses a .htpasswd file to authenticate user logins, and if {AllowLoginName} is set to true uses the TWikiUsers topic to map from the loginname to a displayed name. In the opposite case, if {AllowLoginName} is false, it does not use the TWikiUsers topic at all, and uses the login name as the displayed name (this is how TWiki.org works).

TWiki::Users::BaseUserMapping implements the mappings for the built in users - TWikiAdmin, TWikiGuest, UnknownUser, TWikiContributor, TWikiRegistrationAgent and the SuperAdminGroup and TWikiBaseGroup Groups. Of these, only the TWikiAdmin can login, and that user has the same password as set to save settings in Configure.

TWiki::LoginManager implementations

Both of the TWiki::LoginManager::ApacheLogin and the TWiki::LoginManager::TemplateLogin classes are derived from TWiki::LoginManager, and implement the following methods: new(), forceAuthentication(), loginUrl(), login(), getUser().

If, for example, you want to use a Cookie created by another package, and use it to auto-authenticate a TWiki user, you can create a new MyCookieTemplateLogin.pm that derives from the TWiki::LoginManager::TemplateLogin class, and just over-rides just the new() and getUser() methods.

example to follow

The TemplateLogin::login() calls TWiki::Users::loginTemplateName() to determine which template to use (defaults to login.tmpl). This mechanism is used by the Base Mapping to show the login.sudo.tmpl to login as Admin.

TWiki::Users::Password implementations

A single default implementation of TWiki::Users::Password is provided with TWiki. This subclasses TWiki::Users::Password to provide implementations of the new, fetchPass, fetchUsers, encrypt, setPassword, removeUser, isManagingEmails, checkPassword, setEmails, findLoginByEmail and error methods that use a .htpasswd file on disc to store users.

for example - HTTPDUserAdminContrib adds DBM and SQL authentication to TWiki - allowing TWiki to use, and even create new users.

---

-- Contributors: SvenDowideit, CrawfordCurrie

Related: AddTWikiAdminUser, RefactorUsersCode, MergeFuncUsersContribWithFunc, CaseInsensitiveUserMapping

Discussion