NAME

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

VERSION

version 0.030

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).

SEE ALSO

* Authen::Passphrase

ACKNOWLEDGEMENTS

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

Thanks to Andrew Main for the excellent Authen::Passphrase module.

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/odyniec/p5-Dancer-Plugin-Auth-Basic/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/odyniec/p5-Dancer-Plugin-Auth-Basic

git clone https://github.com/odyniec/p5-Dancer-Plugin-Auth-Basic.git

AUTHOR

Michal Wojciechowski <odyniec@cpan.org>

CONTRIBUTOR

Ovid <curtis@weborama.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Michal Wojciechowski.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.