Hi All,
I am finally starting up work on the Authentication plugin for
CGI::App again. This is purely an interface for Authentication.
Authorization will will be handled in a separate (related) plugin.
What I have done this time is generate documentation and usage
examples first to see if the interface will handle everyhing that is
necesary. What I would like is for some people to have a quick read
of the docs to see if there are any glaring ommisions, or any
structural problems. Also I would aprreciate comments on function
names and such as well.
My goal with this interface it to build an Authentication API that can
be used to authenticate against anything, as long as you are willing
to write a simple driver for it. I would think we could quickly come
up with drivers for the following:
DBI
LDAP
Class::DBI
HTPassword
UnixPassword
CSV
Radius
There is one other abstraction defined in the docs and that is where
to store the authenticated information. I have only mentioned two
right now (Session and Cookie), but there could be others.
Effectively we need a place to store some inforation that can be
retrieved on the next request to check and see if the user is already
logged in. Usually a session is used for that, but you could easily
do it with an encrypted cookie to remove the need to any server side
storage.
I also want to be able to handle Ticket based authentication, where
the actual login may happen on a different server, and we verify that
the ticket we received is valid.
There is one more feature that I haven't had time to integrate into
the docs, and that is the ability to fall back on multiple auth
methods. So you could configure the system to check a local
htpassword file first, but if that failed, check the company wide LDAP
directory next...
Most of the work in this system will happen behind the scenes. All
the developer should be required to do is provide configuration
parameters and indicate which runmodes are protected. The rest will
happen automatically. Even a default login page will be provided if
the developer chooses not to create their own.
Anyway, here are the docs as I have written them so far. They are
quite rough still, but should give an idea of what I am trying to do
here. Please respond with some indication of whether you like it or
dislike it. I really don't mind negative feedback (it is much better
than no feedback :) ). Private responses are OK with me if you don't
want to respond on the list.
Cheers,
Cees
NAME
CGI::Application::Plugin::Auth - Authentication framework for
CGI::Application
SYNOPSIS
use base qw(CGI::Application);
use CGI::Application::Plugin::Auth;
sub myrunmode: Runmode, RequireAuth {
my $self = shift;
# The user should be logged in if we got here
my $username = $self->auth->user;
}
DESCRIPTION
CGI::Application::Plugin::Auth adds the ability to authenticate
users in your CGI::Application modules.
METHODS
auth
This is the only method exported from this module. Everything is
controlled through this method call, which will return a
CGI::Application::Plugin::Auth object, or just the class name if
called as a class method. When using the plugin, you will always
first call $self->auth or __PACKAGE__->auth and then the method you
wish to invoke. For example:
__PACKAGE__->auth->config(
LOGIN_RUNMODE => 'login',
);
- or -
$self->auth->protected_runmodes(qw(one two));
The following methods can all be called on the return value of a
call to ->auth.
config
This method is used to configure the CGI::Application::Plugin::Auth
module. It can be called as an object method, or as a class method.
The following parameters are accepted:
AUTH_TYPE
Here you can choose which authentication module you want to use
to perform the authentication. The default is to use the
CGI::Application::Plugin::Auth::Type::HTPassword which will look
up the username and password in a .htpassword file. For
simplicity, you can leave off the
CGI::Application::Plugin::Auth::Type:: part and just use
'HTPassword' when specifying the AUTH_MODULE parameter. If this
module requires extra parameters, you can pass an array
reference that contains as the first parameter the name of the
module, and as the second parameter a hashref of options for
this module.
AUTH_TYPE => 'Dummy'
- or -
AUTH_TYPE => [ 'HTPassword', { file => '.htpassword' } ],
AUTH_STORE
Here you can choose how we store the authenticated information
after a user has successfully logged in. We need to store the
userid so that on the next request we can tell the user has
already logged in, and we do not have to present them with
another login form. By default a simple Cookie will be used to
store the auth information. If the module requires extra
parameters, you can pass an array reference that contains as the
first parameter the name of the module, and as the second
parameter a hashref of options for this module. These storage
modules generally live under the
CGI::Application::Plugin::Auth::Store:: namespace, and this part
of the package name can be left off when specifying the
AUTH_STORE parameter.
AUTH_STORE => 'Session'
- or -
AUTH_STORE => ['Cookie', { name => 'MYAuthCookie' }]
LOGIN_RUNMODE
Here you can specify a runmode that the user will be redirected
to if they need to login.
LOGIN_RUNMODE => 'login'
LOGIN_DESTINATION
If your login page is external to this module, then you can use
this option to specify a URL that the user will be redirected to
when they need to login. If both LOGIN_DESTINATION and
LOGIN_RUNMODE are specified, then the latter will take
precedence.
LOGIN_DESTINATION => 'http://example.com/login.cgi'
LOGOUT_RUNMODE
Here you can specify a runmode that the user will be redirected
to if they ask to logout.
LOGOUT_RUNMODE => 'logout'
LOGOUT_DESTINATION
If your logout page is external to this module, then you can use
this option to specify a URL that the user will be redirected to
when they ask to logout. If both LOGOUT_DESTINATION and
LOGOUT_RUNMODE are specified, then the latter will take
precedence.
LOGIN_DESTINATION => 'http://example.com/logout.html'
USERNAME_PARAM
Set this to the name of the form field where the user will type
in their username. By default this is set to 'auth_username'.
Both this option and PASSWORD_PARAM should be set to a value
that you are not likely to use in any other forms. This is
important because this plugin will automatically look for query
parameters that match these values if the user is not currently
logged in, and perform the login authentication. So if you use
the same parameter names on a user management page, you may
inadvertantly perform a login when that was not intended.
USERNAME_PARAM => 'auth_username',
PASSWORD_PARAM
Set this to the name of the form field where the user will type
in their password. By default this is set to 'auth_password'.
PASSWORD_PARAM => 'auth_password',
protected_runmodes
This method takes a list of runmodes that are to be protected by
authentication. If a user tries to access one of these runmodes,
then they will be redirected to a login page unless they are
properly logged in. The runmode names can be a list of simple
strings, regular expressions, or special directives that start with
a colon
:all - All runmodes in this module will require authentication
:none - no runmodes in this module will require authentication
# match all runmodes
__PACKAGE__->protected_runmodes(':all');
# only protect runmodes one two and three
__PACKAGE__->protected_runmodes(qw(one two three));
# protect only runmodes that start with auth_
__PACKAGE__->protected_runmodes(qr/^auth_/);
user
This will return the username of the currently logged in user, or
undef if no user is currently logged in.
my $user = $self->auth->user;
is_authenticated
This will return true or false depending on the login status of this
user
assert($self->auth->is_authenticated); # The user should be
logged in if we got here
is_new_login
This will return true or false depending on if this is a fresh login
$self->log->info("New Login") if $self->auth->is_new_login;
login_attempts
This will return the number of failed login attempts for the current
user. It is not always accurate, so it should not be depended upon.
This number is cleared upon a successful login.
logout
This will attempt to logout the user.
$self->auth->logout();
login
This method should in most cases not be used, since it will
automatically be called for you. When it is called, it will attempt
to authenticate the credentials that were passed to the function. It
returns the userid of the logged in user, or undef on login failure.
$self->auth->login($username, $password);
EXAMPLE
In a CGI::Application module:
use CGI::Application::Plugin::AutoRunmode;
use CGI::Application::Plugin::Auth;
use base qw(CGI::Application);
__PACKAGE__->auth->config(
AUTH_TYPE => [ 'HTPassword', { file => '.htpasswd' } ],
AUTH_STORE => 'Session',
LOGIN_RUNMODE => 'login',
LOGOUT_DESTINATION => '/',
USERNAME_PARAM => 'auth_username',
PASSWORD_PARAM => 'auth_passphrase',
);
__PACKAGE__->auth->protected_runmodes(qr/^auth_/, 'another_runmode');
sub login : RunMode {
my $self = shift;
# display a login form here
}
sub one : RunMode, RequireAuth {
my $self = shift;
# The user will only get here if they are logged in
}
sub auth_two : RunMode {
my $self = shift;
# This is also protected because of the
# regexp call to protected_runmodes above
}
BUGS
This is alpha software and as such, the features and interface are
subject to change. So please check the Changes file when upgrading.
SEE ALSO
CGI::Application, perl(1)
AUTHOR
Cees Hek <[EMAIL PROTECTED]>
LICENSE
Copyright (C) 2005 SiteSuite
This library is free software. You can modify and or distribute it
under the same terms as Perl itself.
---------------------------------------------------------------------
Web Archive: http://www.mail-archive.com/cgiapp@lists.erlbaum.net/
http://marc.theaimsgroup.com/?l=cgiapp&r=1&w=2
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
