/ 
Dancer-Plugin-Auth-Basic-0.021
River stage zero No dependents
/ Dancer::Plugin::Auth::Basic

NAME

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

VERSION

Version 0.02

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:

  • password

    Password (if a single user is allowed access).

  • realm

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

  • 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

users

Defines top-level users and their passwords. These users can access all paths configured using the paths option.

Example:

plugins:
  "Auth::Basic":
    users:
      fred: FredsPassword
      jim: JimsPassword

PASSWORDS

Passwords in configuration files can be written as clear text, or in any scheme that is recognized by Authen::Passphrase (either in RFC 2307 or crypt encoding).

Example:

plugins:
 "Auth::Basic":
   users:
     # Clear text
     tom: TomsPassword
     # MD5 hash, RFC 2307 encoding
     ben: "{MD5}X8/UHlR6EiFbFz/0f903OQ=="
     # Blowfish, crypt encoding
     ryan: "$2a$08$4DqiF8T1kUfj.nhxTj2VhuUt1ZX8L.y4aNA3PCAjWLfLEZCw8r0ei"

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

Michael Vu, <micvu 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:

ACKNOWLEDGEMENTS

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

LICENSE AND COPYRIGHT

Copyright 2011-2012 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.