CGI-Application-Plugin-Authentication
view release on metacpan or search on metacpan
NAME
CGI::Application::Plugin::Authentication - Authentication framework for
CGI::Application
SYNOPSIS
package MyCGIApp;
use base qw(CGI::Application); # make sure this occurs before you load the plugin
use CGI::Application::Plugin::Authentication;
MyCGIApp->authen->config(
DRIVER => [ 'Generic', { user1 => '123' } ],
);
MyCGIApp->authen->protected_runmodes('myrunmode');
sub myrunmode {
my $self = shift;
# The user should be logged in if we got here
my $username = $self->authen->username;
}
DESCRIPTION
CGI::Application::Plugin::Authentication adds the ability to
authenticate users in your CGI::Application modules. It imports one
method called 'authen' into your CGI::Application module. Through the
authen method you can call all the methods of the
CGI::Application::Plugin::Authentication plugin.
There are two main decisions that you need to make when using this
module. How will the usernames and password be verified (i.e. from a
database, LDAP, etc...), and how can we keep the knowledge that a user
has already logged in persistent, so that they will not have to enter
their credentials again on the next request (i.e. how do we 'Store' the
authentication information across requests).
Choosing a Driver
There are three drivers that are included with the distribution. Also,
there is built in support for all of the Authen::Simple modules (search
CPAN for Authen::Simple for more information). This should be enough to
cover everyone's needs.
If you need to authenticate against a source that is not provided, you
can use the Generic driver which will accept either a hash of
username/password pairs, or an array of arrays of credentials, or a
subroutine reference that can verify the credentials. So through the
Generic driver you should be able to write your own verification system.
There is also a Dummy driver, which blindly accepts any credentials
(useful for testing). See the
CGI::Application::Plugin::Authentication::Driver::Generic,
CGI::Application::Plugin::Authentication::Driver::DBI and,
CGI::Application::Plugin::Authentication::Driver::Dummy docs for more
information on how to use these drivers. And see the Authen::Simple
suite of modules for information on those drivers.
Choosing a Store
The Store modules keep information about the authentication status of
the user persistent across multiple requests. The information that is
stored in the store include the username, and the expiry time of the
login. There are two Store modules included with this distribution. A
Session based store, and a Cookie based store. If your application is
already using Sessions (through the CGI::Application::Plugin::Session
module), then I would recommend that you use the Session store for
authentication. If you are not using the Session plugin, then you can
use the Cookie store. The Cookie store keeps all the authentication in a
cookie, which contains a checksum to ensure that users can not change
the information.
If you do not specify which Store module you wish to use, the plugin
will try to determine the best one for you.
Login page
The Authentication plugin comes with a default login page that can be
used if you do not want to create a custom login page. This login form
will automatically be used if you do not provide either a LOGIN_URL or
LOGIN_RUNMODE parameter in the configuration. If you plan to create your
own login page, I would recommend that you start with the HTML code for
the default login page, so that your login page will contain the correct
form fields and hidden fields.
Ticket based authentication
This Authentication plugin can handle ticket based authentication
systems as well. All that is required of you is to write a Store module
that can understand the contents of the ticket. The Authentication
plugin will require at least the 'username' to be retrieved from the
ticket. A Ticket based authentication scheme will not need a Driver
module at all, since the actual verification of credentials is done by
an external authentication system, possibly even on a different host.
You will need to specify the location of the login page using the
LOGIN_URL configuration variable, and unauthenticated users will
automatically be redirected to your ticket authentication login page.
EXPORTED METHODS
authen
This is the only method exported from this module. Everything is
controlled through this method call, which will return a
CGI::Application::Plugin::Authentication object, or just the class name
if called as a class method. When using the plugin, you will always
first call $self->authen or __PACKAGE__->authen and then the method you
wish to invoke. For example:
__PACKAGE__->authen->config(
LOGIN_RUNMODE => 'login',
);
- or -
$self->authen->protected_runmodes(qw(one two));
METHODS
config
This method is used to configure the
CGI::Application::Plugin::Authentication module. It can be called as an
object method, or as a class method. Calling this function, will not
itself generate cookies or session ids.
The following parameters are accepted:
DRIVER
Here you can choose which authentication module(s) you want to use
to perform the authentication. For simplicity, you can leave off the
CGI::Application::Plugin::Authentication::Driver:: part when
specifying the DRIVER name If this module requires extra parameters,
you can pass an array reference that contains as the first parameter
the name of the module, and the rest of the values in the array will
be considered options for the driver. You can provide multiple
drivers which will be used, in order, to check the credentials until
a valid response is received.
DRIVER => 'Dummy' # let anyone in regardless of the password
- or -
DRIVER => [ 'DBI',
DBH => $self->dbh,
TABLE => 'user',
CONSTRAINTS => {
'user.name' => '__CREDENTIAL_1__',
'MD5:user.password' => '__CREDENTIAL_2__'
},
],
- or -
DRIVER => [
[ 'Generic', { user1 => '123' } ],
[ 'Generic', sub { my ($u, $p) = @_; is_prime($p) ? 1 : 0 } ]
],
- or -
DRIVER => [ 'Authen::Simple::LDAP',
host => 'ldap.company.com',
basedn => 'ou=People,dc=company,dc=net'
],
STORE
Here you can choose how we store the authenticated information after
a user has successfully logged in. We need to store the username 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. If you
do not provide the STORE option, then the plugin will look to see if
you are using the CGI::Application::Plugin::Session module and based
on that info use either the Session module, or fall back on the
Cookie module. If the module requires extra parameters, you can pass
an array reference that contains as the first parameter the name of
the module, and the rest of the array should contain key value pairs
of options for this module. These storage modules generally live
under the CGI::Application::Plugin::Authentication::Store::
name-space, and this part of the package name can be left off when
specifying the STORE parameter.
STORE => 'Session'
- or -
STORE => ['Cookie',
NAME => 'MYAuthCookie',
SECRET => 'FortyTwo',
EXPIRY => '1d',
]
POST_LOGIN_RUNMODE
Here you can specify a runmode that the user will be redirected to
if they successfully login.
POST_LOGIN_RUNMODE => 'welcome'
my $last_login = $self->authen->last_login;
This function will initiate a session or cookie if one has not been
created already.
last_access
This will return return the time of the last access for this user
my $last_access = $self->authen->last_access;
This function will initiate a session or cookie if one has not been
created already.
is_login_timeout
This will return true or false depending on whether the users login
status just timed out
$self->add_message('login session timed out') if $self->authen->is_login_timeout;
This function will initiate a session or cookie if one has not been
created already.
is_authenticated
This will return true or false depending on the login status of this
user
assert($self->authen->is_authenticated); # The user should be logged in if we got here
This function will initiate a session or cookie if one has not been
created already.
login_attempts
This method will return the number of failed login attempts have been
made by this user since the last successful login. This is not a number
that can be trusted, as it is dependent on the underlying store to be
able to return the correct value for this user. For example, if the
store uses a cookie based session, the user trying to login could delete
their cookies, and hence get a new session which will not have any login
attempts listed. The number will be cleared upon a successful login.
This function will initiate a session or cookie if one has not been
created already.
username
This will return the username of the currently logged in user, or undef
if no user is currently logged in.
my $username = $self->authen->username;
This function will initiate a session or cookie if one has not been
created already.
is_new_login
This will return true or false depending on if this is a fresh login
$self->log->info("New Login") if $self->authen->is_new_login;
This function will initiate a session or cookie if one has not been
created already.
credentials
This method will return the names of the form parameters that will be
looked for during a login. By default they are authen_username and
authen_password, but these values can be changed by supplying the
CREDENTIALS parameters in the configuration. Calling this function, will
not itself generate cookies or session ids.
logout
This will attempt to logout the user. If during a request the
Authentication module sees a parameter called 'authen_logout', it will
automatically call this method to log out the user.
$self->authen->logout();
This function will initiate a session or cookie if one has not been
created already.
drivers
This method will return a list of driver objects that are used for
verifying the login credentials. Calling this function, will not itself
generate cookies or session ids.
store
This method will return a store object that is used to store information
about the status of the authentication across multiple requests. This
function will initiate a session or cookie if one has not been created
already.
initialize
This does most of the heavy lifting for the Authentication plugin. It
will check to see if the user is currently attempting to login by
looking for the credential form fields in the query object. It will load
the required driver objects and authenticate the user. It is OK to call
this method multiple times as it checks to see if it has already been
executed and will just return without doing anything if called multiple
times. This allows us to call initialize as late as possible in the
request so that no unnecessary work is done.
The user will be logged out by calling the logout() method if the login
session has been idle for too long, if it has been too long since the
last login, or if the login has timed out. If you need to know if a user
was logged out because of a time out, you can call the
"is_login_timeout" method.
If all goes well, a true value will be returned, although it is usually
not necessary to check.
This function will initiate a session or cookie if one has not been
created already.
display
This method will return the
CGI::Application::Plugin::Authentication::Display object, creating and
caching it if necessary.
login_box
This method will return the HTML for a login box that can be embedded
into another page. This is the same login box that is used in the
default authen_login runmode that the plugin provides.
This function will initiate a session or cookie if one has not been
created already.
new
This method creates a new CGI::Application::Plugin::Authentication
object. It requires as it's only parameter a CGI::Application object.
This method should never be called directly, since the 'authen' method
that is imported into the CGI::Application module will take care of
creating the CGI::Application::Plugin::Authentication object when it is
required. Calling this function, will not itself generate cookies or
session ids.
instance
This method works the same way as 'new', except that it returns the same
Authentication object for the duration of the request. This method
should never be called directly, since the 'authen' method that is
imported into the CGI::Application module will take care of creating the
CGI::Application::Plugin::Authentication object when it is required.
Calling this function, will not itself generate cookies or session ids.
( run in 1.935 second using v1.01-cache-2.11-cpan-39bf76dae61 )