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.

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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.