TWiki User Authentication

TWiki site access control and user activity tracking options

Authentication, or "login", is the process by which a user lets TWiki know who they are.

Authentication isn't just to do with access control. TWiki uses authentication to identify users, and uses those identities to keep track of who made changes, and manage a wide range of personal settings. With authentication enabled, users can personalise their environment and contribute as recognised individuals, instead of anonymous shadows.

TWiki authentication is extremely flexible, and can either stand alone or integrate with existing authentication schemes. You can set up TWiki to require authentication for every access, or set it up to require authentication only for changes. Authentication is also essential for effective access control.

Quick Authentication Test - Use the %WIKIUSERNAME% variable to return your current identity:

• You are TWikiGuest

TWiki supports three default authentication schemes: no authentication, Template Login, and Apache Login. You can select your chosen authentication option through the Security Settings pane in the configure interface.

If you want users to log in, Template Login is the recommended way. Apache Login isn't as flexible, but historically it's been an option so it's still provided in case you want to use it.

No Login

Does exactly what it says on the tin. Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki style. All visitors are given the TWikiGuest default identity, so you can't track individual user activity.

Template Login

If a user tries to access protected content (either views a topic with access restrictions, or attempts a protected operation such as edit) they are redirected to a "login" page.

Template Login uses a TWiki template to ask for a username and password in a web page, and process them using whatever Password Manager you choose (also in the security section of the configuration page).

Enabling Template Login

1. Use the configure interface to enable the TemplateLogin login manager (on the Security Settings pane).
2. Select the appropriate password manager for your system, or provide your own.
3. In TWiki, edit the TWikiRegistrationPub topic, copy the contents, then edit TWikiRegistration and paste, deleting the old contents and replacing them with the contents of TWikiRegistrationPub.
   You can customize the registration form by deleting or adding input tags. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are carried over into the user home page correctly.
   You can customize the default user home page in NewUserTemplate. The same variables get expanded as in the template topics
4. Register yourself in the TWikiRegistration topic.
   Check that a new line with the username and encrypted password is added to the .htpasswd file. If not, you may have got a path wrong, or the permissions may not allow the webserver user to write to that file.
5. Create a new topic to check if authentication works.
6. Edit the TWikiAdminGroup topic in the TWiki:SSECHome web to include users with system administrator status.
   This is a very important step, as users in this group can access all topics, independent of TWiki access controls.

TWikiAccessControl has more information on setting up access controls.

At this time TWikiAccessControls cannot control access to files in the pub area, unless they are only accessed through the viewfile script. If your pub directory is set up in the webserver to allow open access you may want to add .htaccess files in there to restrict access.

Apache Login

Using this method TWiki does not authenticate users internally. Instead it depends on the REMOTE_USER environment variable, which is set when you enable authentication in the webserver.

The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules such as mod_auth_ldap or mod_auth_mysql you can just plug in directly to them.

TWiki maps the REMOTE_USER that was used to log in to the webserver to a WikiName using the table in TWikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver login name is used for their signature) or register (in which case that login name is mapped to their WikiName).

The same private .htpasswd file used in TWiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support. This allows the TWiki registration support to maintain usernames and passwords.

Enabling Apache Login using mod_auth

You can also use any other Apache authentication module that sets REMOTE_USER

1. Use configure to select the ApacheLogin login manager.
2. Use configure to set up TWiki to create the right kind of .htpasswd entries.
3. Create a .htaccess file in the twiki/bin directory.
   There is an template for this file in twiki/bin/.htaccess.txt that you can copy and change. The comments in the file explain what need to be done.
   If you got it right, the browser should now ask for login name and password when you click on the Edit. If .htaccess does not have the desired effect, you may need to "AllowOverride All" for the directory in httpd.conf (if you have root access; otherwise, email web server support)
   At this time TWikiAccessControls do not control access to files in the pub area, unless they are only accessed through the viewfile script. If your pub directory is set up to allow open access you may want to add .htaccess files in there as well to restrict access
4. In TWiki, edit the TWikiRegistrationPub topic, copy the contents, then edit TWikiRegistration and paste, deleting the old contents and replacing them with the contents of TWikiRegistrationPub.
   You can customize the registration form by deleting or adding input tags. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are carried over into the user home page correctly.
   You can customize the default user home page in NewUserTemplate. The same variables get expanded as in the template topics
5. Register yourself in the TWikiRegistration topic.
   Check that a new line with the username and encrypted password is added to the .htpasswd file. If not, you may have got a path wrong, or the permissions may not allow the webserver user to write to that file.
6. Create a new topic to check if authentication works.
7. Edit the TWikiAdminGroup topic in the TWiki:SSECHome web to include users with system administrator status.
   This is a very important step, as users in this group can access all topics, independent of TWiki access controls.

TWikiAccessControl has more information on setting up access controls.

Logons via bin/logon

Any time a user enters a page that needs authentication, they will be forced to log on. However, if you're using Apache Login, then if a user never has a need to authenticate, they may never log on and never retrieve their personal settings. It may be convenient to force then to log on.

The bin/logon script accomplishes this. The bin/logon script must be setup in the bin/.htaccess file to be a script which requires a valid user to authenticate. However, once authenticated, it will simply redirect the user to the view URL for the page from which logon was linked.

Sessions

TWiki uses the CPAN:CGI::Session and CPAN:CGI::Cookie modules to track sessions using cookies. These modules are de facto standards for session management among Perl programmers. If you can't use Cookies for any reason, CPAN:CGI::Session also supports session tracking using IP matching. However this is inherently insecure and you are strongly advised against it.

There are a number of TWikiVariables available that you can use to interrogate your current session. You can even add your own session variables to the TWiki cookie. Session variables are referred to as "sticky" variables.

Getting, Setting, and Clearing Session Variables

You can get, set, and clear session variables from within TWiki web pages or by using script parameters. This allows you to use the session as a personal "persistent memory space" that is not lost until the web browser is closed. Also note that if a session variable has the same name as a TWiki preference, the session variables value takes precedence over the TWiki preference. This allows for per-session preferences.

To make use of these features, use the tags:

%SESSION_VARIABLE{ "varName" }%
%SESSION_VARIABLE{ "varName" set="varValue" }%
%SESSION_VARIABLE{ "varName" clear="" }%

The session variables can also be set and cleared via CGI variables (include more than one in the string if necessary, separated by commas, as demonstrated here):

set_session_variable=" varName = varValue , varName = varValue , ... "
clear_session_variable=" varName , varName , ..."

That is, to set the session variable SKIN equal to "gnu" while clearing the session variable TEST, adding this to the end of a TWiki URL should work:

?set_session_variable=SKIN=gnu&clear_session_variable=TEST

Cookies and Transparent Session IDs

TWiki normally uses cookies to store session information on a client computer. Cookies are a common way to pass session information from client to server. TWiki cookies simply hold a unique session identifier that is used to look up a database of session information on the TWiki server.

For a number of reasons, it may not be possible to use cookies. In this case, TWiki has a fallback mechanism; it will automatically rewrite every internal URL it sees on pages being generated to one that also passes session information.

TWiki Username vs. Login Username

This section applies only if you are using authentication with existing login names (i.e. mapping from login names to WikiNames).

TWiki internally manages two usernames: Login Username and TWiki Username.

• Login Username: When you login to the intranet, you use your existing login username, ex: pthoeny. This name is normally passed to TWiki by the REMOTE_USER environment variable, and used internally. Login Usernames are maintained by your system administrator.

• TWiki Username: Your name in WikiNotation, ex: PeterThoeny, is recorded when you register using TWikiRegistration; doing so also generates a personal home page in the SSECHome web.

TWiki can automatically map an Intranet (Login) Username to a TWiki Username, provided that the username pair exists in the TWikiUsers topic. This is also handled automatically when you register.

• In the original TWiki distribution, in twiki/data, there are two registration form topics, TWikiRegistration and TWikiRegistrationPub. The original form includes an intranet Login Username field. For Basic Authentication, the original form is replaced by the Pub version. If you started using TWiki on Basic Authentication and want to change, you have to switch back forms for future use, and manually correct the existing entries, by editing TWikiUsers, adding the Login Username for each member - PeterThoeny - pthoeny - 01 Jan 1999 - and also in the .htpasswd file, where you can either replace the WikiNames or duplicate the entries and have both, so both usernames will work.

NOTE: To correctly enter a WikiName - your own or someone else's - be sure to include the SSECHome web name in front of the Wiki username, followed by a period, and no spaces. Ex:

SSECHome.WikiUsername or %MAINWEB%.WikiUsername

This points WikiUser to the SSECHome web, where user registration pages are stored, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic^? everywhere but in the SSECHome web.

Changing Passwords

If your authentication method supports password changing, you can change and reset passwords using forms on regular pages.

• The ChangePassword form ( TWiki/ChangePassword ):
• The ResetPassword form ( TWiki/ResetPassword ):

Related Topics: AdminDocumentationCategory