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.
