Application Based Authentication for TWiki

From Dakar, this plugin is assumed obsolete as per author's Oct 2006 comment in ApplicationAuthenticationAddOnDev

Introduction

TWiki depends on the Web-Server(in most cases-apache) to authenticate the users. The presentation of the UI to take the input of Username and Password depends on User-Agent(web browser) and Web-Server. In this case:

• TWiki has no control over how the browser presents the UI to user.
• There is no decent logout mechanism.
• It has no decent login/logout status indicator.

This Add-On Helps TWiki Administrator to configure the TWiki to use "Application" based authentication method to authenticate the Users. In this approach, TWiki itself provides login box as a part of web page(like most applications do). It therefore control the look and feel, placement and contents of this box. It also explains how to use SSL-based security for login process.

This Add-On provides the:

• A new login and logout scripts that provide handle on how you would want to implement authentication, and enable SessionPlugin to use the authentication.
• Also provides Apache module (Apache::TWikiAuthen) which is used for attachments access control. The access control rule of topic which hold attachments is applied to the attachments.
• Provides information on how to provide Login form and login/logout status indicator.

Third Party Packages

Apache-SSL server

Apache-SSL server is required. The best configuration would be to install the Apache-SSL server on the same server where TWiki is installed. E.g. the example.com should provide Apache-SSL service if TWiki is installed on example.com. Apache-SSL is used to authenticate the user over a secured tunnel.

SessionPlugin

The SessionPlugin is required to create and track the user session.

SpreadSheetPlugin

The SpreadSheetPlugin is required. This plugin is used to indicate the status of logged in user on TWiki and to provide the Login/Logout button according to the status of the user.

Add-On Packages

The Add-On packages are provided with the attachment ApplicationAuthAddOn.zip with this topic. You need to unzip the file in TWiki root directory, the unzip gives files as described below:

File	Description
bin-ssl/do_login	Used for User Authentication process using SSL tunnel, Usage TWiki's local htpasswd method for authenticating users
bin-ssl/do_login_imap	This is optional script. Used for User Authentication process using SSL tunnel,includes method for authenticating users against IMAP Server
bin/do_logout	To logout the user
lib/TWiki/Access.patch	To patch the lib/TWiki/Access.pm module file
TWikiAuthen.tar.gz	Contains the Apache::TWikiAuthen perl module, Attachments respect the Topics ACL

Third Party Packages Installation

Let us assume that we are running TWiki on http://example.com/twiki/bin/view address. The TWiki root directory is /home/httpd/twiki. Let us keep all the scripts which we want to run through SSL inside /home/httpd/twiki/bin-ssl directory, this can be a introduction of new directory in twiki to keep the scripts which are run through SSL tunnel.

Apache-SSL server

The complete installation procedure can be found on the internet. One example site is http://www.linuxhelp.ca/guides/apachessl/ , this site provides step by step installation instructions.

Let us assume Apache-SSL is installed in /usr/local/apachessl/, with configuration file /usr/local/apachessl/conf/httpds.conf. and running on default port 443.

We have to make sure that do_login can be executed through Apache-SSL, this can be done by adding following lines in /usr/local/apachessl/conf/httpds.conf

ScriptAlias /twiki/bin-ssl/ "/home/httpd/twiki/bin-ssl/"
<Directory "/home/httpd/twiki/bin-ssl">
    Options +ExecCGI
    AllowOverride All
    SetHandler cgi-script
    Allow from all
</Directory>

Restart the Apache-SSL server (/usr/local/apachessl/bin/httpsdctl restart)

SessionPlugin

The standard installation of SessionPlugin Plugin is required. The details about this plugin can be found at http://twiki.org/cgi-bin/view/Plugins/SessionPlugin . Please note the %SESSIONLOGONURL% variable is used in do_login script, this information is useful if you face problems with do_login script.

If you are using TWiki in a LAN where user access TWiki through proxy server, it would be better to turn off IP matching configuration in SessionPlugin. This is not requirement but authentication may not work to our expectations if users forget to setup SSL connection proxy. Also is problematic in case proxy servers are configured for sharing the load. The IP matching configuration can be turned off by changing the lines in lib/TWiki/Plugins/SessionPlugin.pm file as follow

use CGI::Session;                       # Uncomment to turn off IP MATCHING (not recommended!!)
#use CGI::Session qw/-ip_match/;         # Uncomment to turn ON IP MATCHING (default! recommended!)

SpreadSheetPlugin

The standard installation of SpreadSheetPlugin Plugin is required. No extra work involved with this. The details about this plugin can be found at http://twiki.org/cgi-bin/view/Plugins/SpreadSheetPlugin .

Add-On Packages Installation and Configuration Instructions

do_login and do_login_imap

The do_login and do_login_imap files are provided with attachments ApplicationAuthAddOn.zip file.

These files are copied into twiki/bin-ssl directory. The do_login file contains the authentication method to authenticate the uses against TWikis local htpasswd database.

The do_login_imap has the procedure of authenticating users against IMAP server. If you are using IMAP for authentication, make sure the perl module Mail-IMAPClient is installed on the system. In this case just copy do_login_imap to do_login script.

do_logout

This script is copied into twiki/bin directory. Configuration not required.

DoLogin Form

Let us create the DoLogin topic in TWiki Web. The reason for creating the Topic in different web is that I do not want the login/logout indicator to appear when Login form is presented to the user. The raw text looks as follow:

---++!! *The Login*
<hr>
<br>
<form action="https://example.com/twiki/bin-ssl/do_login" METHOD="POST">
<table border="0" align="left">
   <tr>
      <td> *Username:* </td>
      <td> <input type="text" name="username" size="25"/> </td>
   </tr>
   <tr>
      <td> *Password:* </td>
      <td> <input type="password" name="password" size="25"/></td>
   </tr>
   <input type="hidden" name="url" value="%URLPARAM{"redurl"}%" />
   <tr>
      <td> </td>
      <td> <input type="submit" value="Login"/> </td>
   </tr>
</table>
</form>
<br>

User Status and Login/Logout button

Let us create the Login/Logout status indicator. First decide where you want the status indicator on your TWiki main page. This document describes the procedure to configure it at WebLeftBar. Add the following lines "WebLeftBar" topic at the beginning.

<style type="text/css">
.button {font-size: 11px; font-weight: bold; color: #000000; text-decoration:none; background-color: #BBC0C2; background-position: center center; clear: none; float: none; padding: 1px; font-family:Verdana, Arial, Helvetica, sans-serif; border:1px #999999 solid;}
</style>

%CALC{"$SET(url1, "http://example.com/bin/view/TWiki/DoLogin")"}% 
%CALC{"$SET(url2, "http://example/bin/do_logout")"}% 
%CALC{"$SET(submit1, "Login")"}% 
%CALC{"$SET(submit2, "Logout")"}% 

<div style="font-size:0.8em;margin:0px;padding:0px;">
%BLUE% %PUBURL%/%TWIKIWEB%/TWikiDocGraphics/person.gif _%USERNAME%_ %ENDCOLOR%
<form style="margin: 0px; padding:0px;"  action=%CALC{"$IF($EXACT(%USERNAME%, guest), $GET(url1), $GET(url2))"}% METHOD="POST">
<input type="hidden" name="redurl" value="%SESSIONLOGONURL%" />
<input class="button" type="submit" value=%CALC{"$IF($EXACT(%USERNAME%,guest), $GET(submit1), $GET(submit2))"}%/>
</form>
</div>

With the TWiki's production release 02 Sep 2004, "WebLeftBar" topic is included in twiki.pattern.tmpl through form so click on "Login" "Logout" does not work to our expectations. Make the following changes. Change the following block in /home/httpd/twiki/templates/twiki.pattern.tmpl

%TMPL:DEF{"leftbar"}%<div class="twikiLeftBar"><div class="twikiWebIndicator"><b>%WEB%</b></div>
<div class="twikiLeftBarContents"><form name="main" action="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
%INCLUDE{"WebLeftBar"}%</form></div></div>%TMPL:END%

to

%TMPL:DEF{"leftbar"}%<div class="twikiLeftBar"><div class="twikiWebIndicator"><b>%WEB%</b></div>
%INCLUDE{"WebLeftBar"}%</div>%TMPL:END%

Controlling TWikiGuest from Editing

Let us configure the TWiki to "No login to view, require login to edit" type of configurarion.

Add the following line in /home/httpd/twiki/lib/TWiki.cfg file

$allowedGuestActions = "change,rename"; # all, view(include rdiff)

If you want to give access to the TWikiGuest for all activities then just set the above variable = "all". The patch file Access.patch should be used to patch the /home/httpd/twiki/lib/TWiki/Access.pm . This file was copied in /home/httpd/twiki/lib/TWiki directory when we unzip the ApplicationAuthAddOn.zip file in TWiki root.

Use the following commands to patch Access.pm

cd /home/httpd/twiki/lib/TWiki/
patch Access.pm <Access.patch 

The patch adds the following lines in Access.pm file in subroutine checkAccessPermission.

##TWiki Application Based Authentication Addition start. 
    if ($theUserName eq "Main.guest" && $TWiki::allowedGuestActions ne "all")
    {
        my @allowedGuestActionList = split/,/, $TWiki::allowedGuestActions;
        foreach (@allowedGuestActionList) 
        {
            if ($theAccessType eq $_) { return 1; }
        }
        return 0;
    }
## End of Addition.

The patch provided with this document will work for TWiki's production release 04 Sep 2004 & SessionPlugin released at 28 Nov 2004

If you config $mainWebname within TWiki.cfg is different to "Main", you should also change the "Main.guest" to what you set.

Remove .htaccess file

Take the backup of .htaccess file and remove it from /home/httpd/twiki/bin directory. I am assuming you are not using .htaccess for any other special purpose.

Apache::TWikiAuthen

This module is used for implementing ACLs on attachments. This section of document contains the details on installation of Apache::TWikiAuthen module and configuring .htaccess file in /home/httpd/twiki/pub directory.

Installation and configuration of Apache::TWikiAuthen module.

The module is provided with the file TWikiAuthen.tar.gz, attached in this document. The installation instructions are standard, as follows

$ gunzip  -c TWikiAuthen.tar.gz |tar xvf -
$ cd TWikiAuthen
$ perl Makefile.PL
$ make
$su    
--------------Enter root password-------
# make install

Typically this will install TWikiAuthen.pm in /usr/lib/perl5/site_perl/5.8.0/Apache directory.

Just modify the following lines to suit your twiki configuration in /usr/lib/perl5/site_perl/5.8.0/Apache/TWikiAuthen.pm file.

BEGIN{
my $twklib = "/home/httpd/twiki/lib/";
unshift @INC, $twklib;
require '/home/httpd/twiki/bin/setlib.cfg';
};

my $oops = "http://example.com/twiki/bin/oops?template=oopsauth";
my $twikiroot = "/home/httpd/twiki/";

Configuration of .htaccess file in TWiki's "pub" area

The typical .htaccess file should look as follow:

PerlAccessHandler Apache::TWikiAuthen
PerlSetVar Access  NoGuest

Add this file in TWiki's "pub" directory.

The "Access" variable, if it is set equal to "guest", then any user can download the attachments. No ACL for attachments if they know the complete URL of the attachment. The "Access" variable is must variable to set, else it will give the error.

The attachments respect the topic's ACL. Please note that in httpd.conf the "pub" directitory should have the following directives.

<Directory "/home/httpd/twiki/pub">
 Options Indexes FollowSymLinks
 AllowOverride All
 Order allow,deny
 Allow from all
</Directory>

Issues

• User Registration: The new User Registration May not work if "guest" is controlled for any topic "change" activity by $allowedGuestActions variable in TWiki.cfg file. I did not gave any thought on this issue.
• User Logs out automatically: A very few times I noticed the user loosing her login information. The user becomes guest. But reload of page or a couple of browsing the site restores the user information.

License

As required for the publication of all extensions to TWiki, the software is published under the terms of the GNU General Public License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details, published at http://www.gnu.org/copyleft/gpl.html

This work is sponsored by Persistent Systems Pvt. Ltd.

Add-On Info

Add-on Author:	TWiki:Main/SopanShewale
Add-on Version:	16 Mar 2005 (v1.000)
Change History:
16 Mar 2005:	Initial version
CPAN Dependencies:	none
Other Dependencies:	Apache+SSL
Perl Version:	5.005
License:	GPL
Add-on Home:	http://TWiki.org/cgi-bin/view/Plugins/ApplicationAuthenticationAddOn
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/ApplicationAuthenticationAddOnDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/ApplicationAuthenticationAddOnAppraisal

Related Topic: TWikiAddOns

-- TWiki:Main/SopanShewale - 16 Mar 2005

• TWikiAuthen-apache2.patch: Apache2 Patch