NAME Mojolicious::Plugin::Authentication - A plugin to make authentication a bit easier VERSION version 1.17 SYNOPSIS use Mojolicious::Plugin::Authentication $self->plugin('authentication' => { 'session_key' => 'wickedapp', 'load_user' => sub { ... }, 'validate_user' => sub { ... }, }); if ($self->authenticate('username', 'password')) { ... } METHODS authenticate($username, $password) Authenticate will use the supplied load_user and validate_user subroutine refs to see whether a user exists with the given username and password, and will set up the session accordingly. Returns true when the user has been successfully authenticated, false otherwise. user_exists Returns true if an authenticated user exists, false otherwise. user Returns the user object as it was returned from the supplied 'load_user' subroutine ref. logout Removes the session data for authentication, and effectively logs a user out. CONFIGURATION The following options can be set for the plugin: load_user (REQUIRED) A coderef for user loading (see USER LOADING) validate_user (REQUIRED) A coderef for user validation (see USER VALIDATION) session_key (optional) The name of the session key In order to set the session expiry time, use the following in your startup routine: $app->plugin('authentication', { ... }); $app->sessions->default_expiration(86400); # set expiry to 1 day $app->sessions->default_expiration(3600); # set expiry to 1 hour USER LOADING The coderef you pass to the load_user configuration key has the following signature: sub { my ($app, $uid) = @_; ... return $user; } The uid is the value that was originally returned from the validate_user coderef. You must return either a user object (it can be a hashref, arrayref, or a blessed object) or undef. USER VALIDATION User validation is what happens when we need to authenticate someone. The coderef you pass to the validate_user configuration key has the following signatre: sub { my ($app, $username, $password) = @_; ... return $uid; } You must return either a user id or undef. The user id can be numerical or a string. Do not return hashrefs, arrayrefs or objects, since the behaviour of this plugin could get a little bit on the odd side of weird. EXAMPLES For a code example using this, see the t/01-functional.t test, it uses Mojolicious::Lite and this plugin. ROUTING VIA CONDITION This plugin also exports a routing condition you can use in order to limit access to certain documents to only authenticated users. $r->route('/foo')->over(authenticated => 1)->to('mycontroller#foo'); my $authenticated_only = $r->route('/members')->over(authenticated => 1)->to('members#index'); $authenticated_only->route('online')->to('members#online'); If someone is not authenticated, these routes will not be considered by the dispatcher and unless you have set up a catch-all route, a 404 Not Found will be generated instead. ROUTING VIA BRIDGE If you want to be able to send people to a login page, you will have to use the following: my $members_only = $r->route('/members')->to(cb => sub { my $self = shift; $self->redirect_to('/login') and return 0 unless($self->user_exists); return 1; }); $members_only->route('online')->to('members#online'); SEE ALSO Mojolicious::Sessions AUTHOR Ben van Staveren, "" BUGS / CONTRIBUTING Please report any bugs or feature requests through the web interface at . SUPPORT You can find documentation for this module with the perldoc command. perldoc Mojolicious::Plugin::Authentication You can also look for information at: * AnnoCPAN: Annotated CPAN documentation * CPAN Ratings * Search CPAN ACKNOWLEDGEMENTS Andrew Parker - For pointing out some bugs that crept in; a silent reminder not to code while sleepy Mirko Westermeier (memowe) - For doing some (much needed) code cleanup LICENSE AND COPYRIGHT Copyright 2011 Ben van Staveren. This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See http://dev.perl.org/licenses/ for more information.