Provided by: libdancer-plugin-auth-extensible-perl_0.30-1_all bug

NAME

       Dancer::Plugin::Auth::Extensible - extensible authentication framework for Dancer apps

DESCRIPTION

       A user authentication and authorisation framework plugin for Dancer apps.

       Makes it easy to require a user to be logged in to access certain routes, provides role-
       based access control, and supports various authentication methods/sources (config file,
       database, Unix system users, etc).

       Designed to support multiple authentication realms and to be as extensible as possible,
       and to make secure password handling easy (the base class for auth providers makes
       handling "RFC2307"-style hashed passwords really simple, so you have no excuse for storing
       plain-text passwords).

SYNOPSIS

       Configure the plugin to use the authentication provider class you wish to use:

         plugins:
               Auth::Extensible:
                   realms:
                       users:
                           provider: Example
                           ....

       The configuration you provide will depend on the authentication provider module in use.
       For a simple example, see Dancer::Plugin::Auth::Extensible::Provider::Config.

       Define that a user must be logged in and have the proper permissions to access a route:

           get '/secret' => require_role Confidant => sub { tell_secrets(); };

       Define that a user must be logged in to access a route - and find out who is logged in
       with the "logged_in_user" keyword:

           get '/users' => require_login sub {
               my $user = logged_in_user;
               return "Hi there, $user->{username}";
           };

AUTHENTICATION PROVIDERS

       For flexibility, this authentication framework uses simple authentication provider
       classes, which implement a simple interface and do whatever is required to authenticate a
       user against the chosen source of authentication.

       For an example of how simple provider classes are, so you can build your own if required
       or just try out this authentication framework plugin easily, see
       Dancer::Plugin::Auth::Extensible::Provider::Example.

       This framework supplies the following providers out-of-the-box:

       Dancer::Plugin::Auth::Extensible::Provider::Unix
           Authenticates users using system accounts on Linux/Unix type boxes

       Dancer::Plugin::Auth::Extensible::Provider::Database
           Authenticates users stored in a database table

       Dancer::Plugin::Auth::Extensible::Provider::Config
           Authenticates users stored in the app's config

       Need to write your own?  Just subclass Dancer::Plugin::Auth::Extensible::Provider::Base
       and implement the required methods, and you're good to go!

CONTROLLING ACCESS TO ROUTES

       Keywords are provided to check if a user is logged in / has appropriate roles.

       require_login - require the user to be logged in
               get '/dashboard' => require_login sub { .... };

           If the user is not logged in, they will be redirected to the login page URL to log in.
           The default URL is "/login" - this may be changed with the "login_url" option.

       require_role - require the user to have a specified role
               get '/beer' => require_role BeerDrinker => sub { ... };

           Requires that the user be logged in as a user who has the specified role.  If the user
           is not logged in, they will be redirected to the login page URL.  If they are logged
           in, but do not have the required role, they will be redirected to the access denied
           URL.

       require_any_roles - require the user to have one of a list of roles
               get '/drink' => require_any_role [qw(BeerDrinker VodaDrinker)] => sub {
                   ...
               };

           Requires that the user be logged in as a user who has any one (or more) of the roles
           listed.  If the user is not logged in, they will be redirected to the login page URL.
           If they are logged in, but do not have any of the specified roles, they will be
           redirected to the access denied URL.

       require_all_roles - require the user to have all roles listed
               get '/foo' => require_all_roles [qw(Foo Bar)] => sub { ... };

           Requires that the user be logged in as a user who has all of the roles listed.  If the
           user is not logged in, they will be redirected to the login page URL.  If they are
           logged in but do not have all of the specified roles, they will be redirected to the
           access denied URL.

   Replacing the Default " /login " and " /login/denied " Routes
       By default, the plugin adds a route to present a simple login form at that URL.  If you
       would rather add your own, set the "no_default_pages" setting to a true value, and define
       your own route which responds to "/login" with a login page.

       If the user is logged in, but tries to access a route which requires a specific role they
       don't have, they will be redirected to the "permission denied" page URL, which defaults to
       "/login/denied" but may be changed using the "denied_page" option.

       Again, by default a route is added to respond to that URL with a default page; again, you
       can disable this by setting "no_default_pages" and creating your own.

       This would still leave the routes "post '/login'" and "any '/logout'" routes in place. To
       disable them too, set the option "no_login_handler" to a true value. In this case, these
       routes should be defined by the user, and should do at least the following:

           post '/login' => sub {
               my ($success, $realm) = authenticate_user(
                   params->{username}, params->{password}
               );
               if ($success) {
                   session logged_in_user => params->{username};
                   session logged_in_user_realm => $realm;
                   # other code here
               } else {
                   # authentication failed
               }
           };

           any '/logout' => sub {
               session->destroy;
           };

       If you want to use the default "post '/login'" and "any '/logout'" routes you can
       configure them. See below.

   Keywords
       require_login
           Used to wrap a route which requires a user to be logged in order to access it.

               get '/secret' => require_login sub { .... };

       require_role
           Used to wrap a route which requires a user to be logged in as a user with the
           specified role in order to access it.

               get '/beer' => require_role BeerDrinker => sub { ... };

           You can also provide a regular expression, if you need to match the role using a regex
           - for example:

               get '/beer' => require_role qr/Drinker$/ => sub { ... };

       require_any_role
           Used to wrap a route which requires a user to be logged in as a user with any one (or
           more) of the specified roles in order to access it.

               get '/foo' => require_any_role [qw(Foo Bar)] => sub { ... };

       require_all_roles
           Used to wrap a route which requires a user to be logged in as a user with all of the
           roles listed in order to access it.

               get '/foo' => require_all_roles [qw(Foo Bar)] => sub { ... };

       logged_in_user
           Returns a hashref of details of the currently logged-in user, if there is one.

           The details you get back will depend upon the authentication provider in use.

       user_has_role
           Check if a user has the role named.

           By default, the currently-logged-in user will be checked, so you need only name the
           role you're looking for:

               if (user_has_role('BeerDrinker')) { pour_beer(); }

           You can also provide the username to check;

               if (user_has_role($user, $role)) { .... }

       user_roles
           Returns a list of the roles of a user.

           By default, roles for the currently-logged-in user will be checked; alternatively, you
           may supply a username to check.

           Returns a list or arrayref depending on context.

       authenticate_user
           Usually you'll want to let the built-in login handling code deal with authenticating
           users, but in case you need to do it yourself, this keyword accepts a username and
           password, and optionally a specific realm, and checks whether the username and
           password are valid.

           For example:

               if (authenticate_user($username, $password)) {
                   ...
               }

           If you are using multiple authentication realms, by default each realm will be
           consulted in turn.  If you only wish to check one of them (for instance, you're
           authenticating an admin user, and there's only one realm which applies to them), you
           can supply the realm as an optional third parameter.

           In boolean context, returns simply true or false; in list context, returns "($success,
           $realm)".

   SAMPLE CONFIGURATION
       In your application's configuation file:

           session: simple
           plugins:
               Auth::Extensible:
                   # Set to 1 if you want to disable the use of roles (0 is default)
                   disable_roles: 0
                   # After /login: If no return_url is given: land here ('/' is default)
                   user_home_page: '/user'
                   # After /logout: If no return_url is given: land here (no default)
                   exit_page: '/'

                   # List each authentication realm, with the provider to use and the
                   # provider-specific settings (see the documentation for the provider
                   # you wish to use)
                   realms:
                       realm_one:
                           provider: Database
                               db_connection_name: 'foo'

       Please note that you must have a session provider configured.  The authentication
       framework requires sessions in order to track information about the currently logged in
       user.  Please see Dancer::Session for information on how to configure session management
       within your application.

AUTHOR

       David Precious, "<davidp at preshweb.co.uk>"

BUGS / FEATURE REQUESTS

       This is an early version; there may still be bugs present or features missing.

       This is developed on GitHub - please feel free to raise issues or pull requests against
       the repo at: <https://github.com/bigpresh/Dancer-Plugin-Auth-Extensible>

ACKNOWLEDGEMENTS

       Valuable feedback on the early design of this module came from many people, including Matt
       S Trout (mst), David Golden (xdg), Damien Krotkine (dams), Daniel Perrett, and others.

       Configurable login/logout URLs added by Rene (hertell)

       Regex support for require_role by chenryn

       Support for user_roles looking in other realms by Colin Ewen (casao)

       LDAP provider added by Mark Meyer (ofosos)

       Config options for default login/logout handlers by Henk van Oers (hvoers)

LICENSE AND COPYRIGHT

       Copyright 2012-13 David Precious.

       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.