NAME
    Dancer2::Plugin::HTTP::Auth::Extensible

VERSION
    version 0.003

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

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

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

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

        get '/secret' => http_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' => http_require_authentication sub {
            my $user = http_authenticated_user;
            return "Hi there, $user->{username}";
        };

DESCRIPTION
    A user authentication and authorisation framework plugin for Dancer2
    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).

NAME
    Dancer2::Plugin::HTTP::Auth::Extensible - extensible authentication
    framework for Dancer2 apps

AUTHENTICATION PROVIDERS
    This framework builds on top of Dancer2::Plugin::Auth::Extensible. For a
    full explenation of the providers check that manual.

    For flexibility, that 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 Dancer2::Plugin::Auth::Extensible::Provider::Example.

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

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

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

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

    Need to write your own? Just subclass
    Dancer2::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.

    http_require_authentication - require the user to be authenticated
            get '/dashboard' => http_require_authentication sub { .... };

        If the user can not be authenticated, they will be recieve a HTTP
        response status of "/401 Not Authorized". Remember, it should
        actualy say 'Not Authenticated'.

        Optionally, a realm name can be specified as an extra argument:

            get 'outer_space'
                => http_require_authentication 'outer_space'
                => sub { .... };

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

        Requires that the user can be authenticated as a user who has the
        specified role. If the user can not be authenticated, they will get
        a "401 Unautorized" response. If they are logged in, but do not have
        the required role, they will recieve a "403 Forbidden" response.

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

        Same as http_require_role except that a user has any one (or more)
        of the roles listed.

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

        Same as http_require_role except that a user has all of the roles
        listed.

  Replacing the Default  401  and  403  Pages
  Keywords
    http_require_authentication
        Used to wrap a route which requires a user can be authenticated to
        access it.

            get '/secret' => http_require_authentication sub { .... };
            get '/secret' => http_require_authentication 'realm-name' sub { .... };

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

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

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

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

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

            get '/foo' => http_require_any_role [qw(Foo Bar)] => sub { ... };
            get '/foo' => http_require_any_role [qw(Foo Bar)] 'realm-name' => sub { ... };

    http_require_all_roles
        Used to wrap a route which requires a user can be authenticated with
        all of the roles listed in order to access it.

            get '/foo' => http_require_all_roles [qw(Foo Bar)] => sub { ... };
            get '/foo' => http_require_all_roles [qw(Foo Bar)] 'realm-name' => sub { ... };

    authenticated_user
        Returns a hashref of details of the currently authenticated 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 authentication 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)".

    http_username - gets or sets the name of the authenticated user
        WARNING: setting the username will issue a "SECURITY BREACH"
        warning. You rarely want to impersonate another user.

            $my username = http_username;
            http_username('new name');
            http_username 'new name';

        If not inside an authenticated route (there is no authenticated
        user), " http_username " returns undef.

    http_realm - gets or sets the real of the current request
        WARNING: setting the realm will issue a "SECURITY BREACH" warning.
        You rarely want to switch to another realm

            $my realm = http_realm;
            http_realm('new name');
            http_realm 'new name';

        If not inside an authenticated route (there is no authenticated
        user), " http_realm " returns undef.

  SAMPLE CONFIGURATION
    In your application's configuation file:

        plugins:
            HTTP::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'
            
                default_realm: realm_xxx
                # If there is more than one realm, is needed if no 'realm' is
                # specified in http_requires_authentication.

    Please note that you not have to have a session provider configured. The
    authentication framework does not require sessions in order to track
    information about the currently logged in user.

AUTHOR
    Theo van Hoesel, "<Th.J.v.Hoesel at THEMA-MEDIA dot nl>"

    HTTP Autneticate implementation based on:

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

    Dancer2 port of Dancer::Plugin::Auth::Extensible by:

    Stefan Hornburg (Racke), "<racke at linuxia.de>"

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/THEMA-MEDIA/Dancer2-Plugin-HTTP-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 2014 THEMA-MEDIA, Th.J. van Hoesel

    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.

AUTHOR
    Theo van Hoesel <Th.J.v.Hoesel@THEMA-MEDIA.nl>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2014 by THEMA-MEDIA, Th. J. van Hoesel.

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

