NAME
    Dancer::Plugin::Auth::Htpasswd - Basic HTTP authentication with htpasswd
    files in Dancer apps

VERSION
    Version 0.014

SYNOPSIS
    Dancer::Plugin::Auth::Htpasswd allows you to use Apache-style htpasswd
    files to implement basic HTTP authentication in Dancer web applications.

    Add the plugin to your application:

        use Dancer::Plugin::Auth::Htpasswd;

    In the configuration file, list the paths that you want to protect and
    the htpasswd files to use:

        plugins:
          "Auth::Htpasswd":
            paths:
              "/restricted": /path/to/htpasswd
              "/secret/documents":
                realm: "Top Secret Documents"
                passwd_file: /different/path/to/htpasswd

    You can also enable authentication by calling the `auth_htpasswd'
    function in a before filter:

        before sub {
            auth_htpasswd realm => 'Secret Files',
                          passwd_file => '/path/to/htpasswd';
        };

    or in a route handler:

        get '/restricted' => sub {
            auth_htpasswd '/path/to/htpasswd';
        
            # Authenticated
            ...
        };

DESCRIPTION
    Dancer::Plugin::Auth::Htpasswd provides a simple way to implement basic
    HTTP authentication in Dancer web applications using Apache-style
    htpasswd files.

CONFIGURATION
    To configure the plugin, add its options in the `plugins' section of
    your application's configuration file. The supported 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:

    * `passwd_file'
        Location of the htpasswd file.

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

    Example:

        plugins:
          "Auth::Htpasswd":
            paths:
              "/classified":
                realm: "Classified Files"
                passwd_file: /path/to/htpasswd
            
    If you don't need to set the realm, you can use the simplified syntax
    with just the location of the htpasswd file:

        plugins:
          "Auth::Htpasswd":
            paths:
              "/secret/documents": /path/to/htpasswd
              "/restricted": /another/path/to/htpasswd

SUBROUTINES
  auth_htpasswd
    Call this function in a before filter or at the beginning of a route
    handler. It checks the specified htpasswd file to verify 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.

    You can call this function with a single parameter, which is the
    location of the htpasswd file to use:

        auth_htpasswd '/path/to/htpasswd';
    
    or, with a hash of parameters:

        auth_htpasswd realm => 'Authorized personnel only',
                      passwd_file => '/path/to/htpasswd';

    Parameters:

    * `passwd_file'
        Location of the htpasswd file.

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

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

BUGS
    Please report any bugs or feature requests to
    `bug-dancer-plugin-auth-htpasswd at rt.cpan.org', or through the web
    interface at
    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dancer-Plugin-Auth-Htpass
    wd. 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::Htpasswd

    You can also look for information at:

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

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

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

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

ACKNOWLEDGEMENTS
    The plugin uses the Authen::Htpasswd module, written by David Kamholz
    and Yuval Kogman.

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.