NAME
    Dancer::Plugin::Auth::Basic - Basic HTTP authentication for Dancer web
    apps

VERSION
    Version 0.01

SYNOPSIS
    Dancer::Plugin::Auth::Basic provides basic HTTP authentication for
    Dancer web applications.

    Add the plugin to your application:

        use Dancer::Plugin::Auth::Basic;

    Configure the protected paths and users/passwords in the YAML
    configuration file:

        plugins:
          "Auth::Basic":
            paths:
              "/restricted":
                realm: Restricted zone
                user: alice
                password: AlicesPassword
              "/secret/data":
                users:
                  alice: AlicesPassword
                  bob: BobsPassword

    You can also call the `auth_basic' function in a before filter:

        before sub {
            auth_basic user => 'alice', password => 'AlicesPassword';
        };

    or in a route handler:

        get '/confidential' => sub {
            auth_basic realm => 'Authorized personnel only',
                users => { 'alice' => 'AlicesPassword', 'bob' => 'BobsPassword' };
        
            # Authenticated
            ...
        };

DESCRIPTION
    Dancer::Plugin::Auth::Basic adds basic HTTP authentication to Dancer web
    applications.

CONFIGURATION
    The available configuration options are listed below.

  paths
    Defines one or more paths that will be protected, including sub-paths
    (so if the path is `"/restricted"', then
    `"/restricted/secret/file.html"' will also be protected). Each path can
    have the following parameters:

    * `realm'
        Realm name that will be displayed in the authentication dialog.
        Default: `"Restricted area"'

    * `password'
        Password (if a single user is allowed access).

    * `user'
        User name (if a single user is allowed access).

    * `users'
        A list of user names and passwords (if multiple users are allowed
        access).

    Example:

        plugins:
          "Auth::Basic":
            paths:
              "/secret":
                realm: "Top secret documents"
                user: charlie
                password: CharliesPassword
              "/documents":
                realm: "Only for Bob and Tim"
                users:
                  bob: BobsPassword
                  tim: TimsPassword

FUNCTIONS
  auth_basic
    This function may be called in a before filter or at the beginning of a
    route handler. It checks if the client is authorized to access the
    requested path -- if not, it immediately returns a 401 Unauthorized
    response to prompt the user to authenticate.

        auth_basic realm => 'Top secret', user => 'alice',
            password => 'AlicesPassword';

    Parameters:

    * `realm'
        Realm name that will be displayed in the authentication dialog.
        Default: `"Restricted area"'

    * `password'
        Password (if a single user is allowed access).

    * `user'
        User name (if a single user is allowed access).

    * `users'
        A hash reference mapping user names to passwords (if multiple users
        are allowed access).

AUTHOR
    Michal Wojciechowski, `<odyniec at cpan.org>'

BUGS
    Please report any bugs or feature requests to
    `bug-dancer-plugin-auth-basic at rt.cpan.org', or through the web
    interface at
    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dancer-Plugin-Auth-Basic.
    I will be notified, and then you'll automatically be notified of
    progress on your bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc Dancer::Plugin::Auth::Basic

    You can also look for information at:

    * RT: CPAN's request tracker
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Dancer-Plugin-Auth-Basic

    * AnnoCPAN: Annotated CPAN documentation
        http://annocpan.org/dist/Dancer-Plugin-Auth-Basic

    * CPAN Ratings
        http://cpanratings.perl.org/d/Dancer-Plugin-Auth-Basic

    * Search CPAN
        http://search.cpan.org/dist/Dancer-Plugin-Auth-Basic/

ACKNOWLEDGEMENTS
    Inspired by Tatsuhiko Miyagawa's Plack::Middleware::Auth::Basic.

LICENSE AND COPYRIGHT
    Copyright 2011 Michal Wojciechowski.

    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.