AuthPagePlugin

This plugin is an add-on to SessionPlugin, designed to support a "logon page" to authenticate access to TWiki. It is designed for use in environments where:

• it is not possible to use Apache authentication, for example, you want to integrate with a corporate login standard, and there is no Apache auth module for it
• you want multiple layers of authentication, for example, BasicAuth to access the site and view pages as a guest, and then some other scheme to allow access to edit)
• you want to logout and login as another user

You have to provide an implementation of the TWiki::Plugins::AuthPagePlugin::Validator::validate method. Two working example implementations, one using the TWiki::User::HtPasswdUser module and the other using Apache::Htpasswd are included.

The plugin works by calling an authentication function for each TWiki bin script that is to be protected. This function checks if the current session is authenticated, and if not, it redirects to a login script. This script prompts for credentials and calls your validator to check the credentials. If the credentials are sound, it caches the result of the validation in the session cookie and redirects to the original URL. The validator results are available from the SessionPlugin session variable VALIDATION, so other plugins can pick them up if needed.

Logged-in users can go back to the login page and log-in as a different user.

The login page is generated from the templates/login.tmpl template, so it can easily be tailored to your requirements.

Note the login process does not use any encoding on passwords - they are sent in plain text. If there is any risk of your browser - to - server communications being tapped you should use SSL (secure sockets layer, or https:)

Plugin Settings

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Authenticate users with a logon page

Plugin Installation Instructions

Note: These instructions are for the TWiki maintainer. No changes to your browser are required.

This plugin requires at least the TWiki20040902 ("Cairo") TWiki release, and the SessionPlugin. The plugin also works on more recent code that Cairo (a.k.a Dakar)

• Download the ZIP file from the Plugin web (see below). Contents:

  File:	Description:
  bin/login	login script
  bin/pre_dakar_login	login script for Cairo release
  templates/login.tmpl	template for login page
  data/TWiki/AuthPagePlugin.txt	documentation topic
  lib/TWiki/Plugins/AuthPagePlugin.pm	main plugin module
  lib/TWiki/Plugins/AuthPagePlugin/Apache_HtPasswd_Validator.pm	example validator
  lib/TWiki/Plugins/AuthPagePlugin/HtPasswdUser_Validator.pm	example validator
  AuthPagePlugin_installer.pl	Install script

• Unzip AuthPagePlugin.zip in your twiki installation directory.
• perl AuthPagePlugin_installer.pl to automatically check and install other TWiki modules that this module depends on. This script also includes an uninstaller should you ever wish to remove the plugin from your installation.
• Alternatively, manually make sure the dependencies listed in the table below are resolved.

  Name	Version	Description
  TWiki::Plugins::SessionPlugin	>=1.000	Required. Provides the basic session maintenance.
  TWiki::Plugins::SpreadSheetPlugin	??	Required. Generates errors in data/warning.txt if not installed.

• If you have a pre-2005 release edit the hard-coded list of script names in lib/TWiki/Plugins/AuthPagePlugin.pm ( look for HARD CODED FOR PRE-2005 RELEASE ) to suit
• Or, if you have a 2005 or later release but you did not run the installer script, you will need to:
  • add the following setting to your LocalSite.cfg
$cfg{AuthPagePlugin}{Scripts} = qr/\b(attach|edit|manage|passwd|rename|resetpasswd|save|upload|viewauth|rdiffauth)\b/;
    This setting defines a perl regular expression that matches the server pathnames of the scripts that are to be protected.
  • Copy the bin/Dakar_login script to bin/login, and set the permissions correctly. (NOTE: This step is no longer required.)
• In all releases, to enable the TWiki::User::HtPasswdUser validator
  • change directory to lib/TWiki/Plugins/AuthPagePlugin
  • copy HtPasswdUser_Validator.pm to Validator.pm
  • If you do not have it installed, you may have to install 'SpreadSheetPlugin' (for example, if you pulled your code from svn...)
• or, to enable the Apache::Htpasswd validator
  • install CPAN:Apache::Htpasswd (http://www.cpan.org)
  • change directory to lib/TWiki/Plugins/AuthPagePlugin
  • copy Apache_Htpasswd_Validator.pm to =Validator.pm
  • edit the .pm file and set up the path to your password file.
• or, write a validator appropriate to your preferred authentication method.

If you are also using standard webserver authentication, then some changes to SessionPlugin are required. SessionPlugin by default assumes that the REMOTE_USER set up by the webserver will be the same as the authorised user. When using AuthPagePlugin that isn't the case, so we need to make some small changes to SessionPlugin. Edit SessionPlugin.pm and comment out the following lines in _init_authuser

        #$session->clear() if( defined($session) && defined($session->param) && 
        #   defined($query) && defined( $query->remote_user() ) &&
        #   defined($authUserSessionVar) &&
        #   defined( $session->param( $authUserSessionVar ) ) &&
        #   "" ne $query->remote_user() && 
        #   "" ne $session->param( $authUserSessionVar ) &&
        #   $query->remote_user() ne $session->param( $authUserSessionVar ) );

        # See whether the user was logged in (first session, then webserver, then default)
        $authUser = #$query->remote_user() ||
                    $session->param( $authUserSessionVar ) || 
                    TWiki::Func::getDefaultUserName();

A future release of SessionPlugin will make this behaviour conditional.

Plugin Info

Plugin Author:	TWiki:Main/CrawfordCurrie
Copyright:	© 2005 Garage Games
Copyright:	© 2005 Crawford Currie http://www.c-dot.co.uk
License:	GNU General Public License
Plugin Version:	1.002
Change History:
30 Mar 2005	1.002 Eliminated need to edit bin scripts. Now works on Cairo and Dakar.
29 Mar 2005	1.001 Added HtPasswdUser_Validator.pm
24 Mar 2005	1.000 First version

TWiki:Plugins/Benchmark:	GoodStyle nn%, FormattedSearch nn%, AuthPagePlugin nn%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/AuthPagePlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/AuthPagePluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/AuthPagePluginAppraisal

This work was sponsored by

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main/CrawfordCurrie - 14:19:52 30 March 2005