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, "<madcat at cpan.org>"

BUGS / CONTRIBUTING
    Please report any bugs or feature requests through the web interface at
    <https://github.com/benvanstaveren/mojolicious-plugin-authentication/iss
    ues>.

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

        <http://annocpan.org/dist/Mojolicious-Plugin-Authentication>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/Mojolicious-Plugin-Authentication>

    *   Search CPAN

        <http://search.cpan.org/dist/Mojolicious-Plugin-Authentication/>

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.