.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Dancer::Plugin::Auth::Extensible 3pm"
.TH Dancer::Plugin::Auth::Extensible 3pm "2016-09-06" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Dancer::Plugin::Auth::Extensible \- extensible authentication framework for Dancer apps
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A user authentication and authorisation framework plugin for Dancer apps.
.PP
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).
.PP
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 \f(CW\*(C`RFC2307\*(C'\fR\-style hashed passwords really simple, so you
have no excuse for storing plain-text passwords.  A simple script to generate
RFC2307\-style hashed passwords is included, or you can use Crypt::SaltedHash
yourself to do so, or use the \f(CW\*(C`slappasswd\*(C'\fR utility if you have it installed.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Configure the plugin to use the authentication provider class you wish to use:
.PP
.Vb 6
\&  plugins:
\&        Auth::Extensible:
\&            realms:
\&                users:
\&                    provider: Example
\&                    ....
.Ve
.PP
The configuration you provide will depend on the authentication provider module
in use.  For a simple example, see
Dancer::Plugin::Auth::Extensible::Provider::Config.
.PP
Define that a user must be logged in and have the proper permissions to 
access a route:
.PP
.Vb 1
\&    get \*(Aq/secret\*(Aq => require_role Confidant => sub { tell_secrets(); };
.Ve
.PP
Define that a user must be logged in to access a route \- and find out who is
logged in with the \f(CW\*(C`logged_in_user\*(C'\fR keyword:
.PP
.Vb 4
\&    get \*(Aq/users\*(Aq => require_login sub {
\&        my $user = logged_in_user;
\&        return "Hi there, $user\->{username}";
\&    };
.Ve
.SH "AUTHENTICATION PROVIDERS"
.IX Header "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.
.PP
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.
.PP
This framework supplies the following providers out-of-the-box:
.IP "Dancer::Plugin::Auth::Extensible::Provider::Unix" 4
.IX Item "Dancer::Plugin::Auth::Extensible::Provider::Unix"
Authenticates users using system accounts on Linux/Unix type boxes
.IP "Dancer::Plugin::Auth::Extensible::Provider::Database" 4
.IX Item "Dancer::Plugin::Auth::Extensible::Provider::Database"
Authenticates users stored in a database table
.IP "Dancer::Plugin::Auth::Extensible::Provider::Config" 4
.IX Item "Dancer::Plugin::Auth::Extensible::Provider::Config"
Authenticates users stored in the app's config
.PP
Need to write your own?  Just subclass
Dancer::Plugin::Auth::Extensible::Provider::Base and implement the required
methods, and you're good to go!
.SH "CONTROLLING ACCESS TO ROUTES"
.IX Header "CONTROLLING ACCESS TO ROUTES"
Keywords are provided to check if a user is logged in / has appropriate roles.
.IP "require_login \- require the user to be logged in" 4
.IX Item "require_login - require the user to be logged in"
.Vb 1
\&    get \*(Aq/dashboard\*(Aq => require_login sub { .... };
.Ve
.Sp
If the user is not logged in, they will be redirected to the login page \s-1URL\s0 to
log in.  The default \s-1URL\s0 is \f(CW\*(C`/login\*(C'\fR \- this may be changed with the
\&\f(CW\*(C`login_page\*(C'\fR option.
.IP "require_role \- require the user to have a specified role" 4
.IX Item "require_role - require the user to have a specified role"
.Vb 1
\&    get \*(Aq/beer\*(Aq => require_role BeerDrinker => sub { ... };
.Ve
.Sp
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 \s-1URL. \s0 If
they are logged in, but do not have the required role, they will be redirected
to the access denied \s-1URL.\s0
.IP "require_any_roles \- require the user to have one of a list of roles" 4
.IX Item "require_any_roles - require the user to have one of a list of roles"
.Vb 3
\&    get \*(Aq/drink\*(Aq => require_any_role [qw(BeerDrinker VodaDrinker)] => sub {
\&        ...
\&    };
.Ve
.Sp
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 \s-1URL. \s0 If they are logged in, but do not have any of the specified
roles, they will be redirected to the access denied \s-1URL.\s0
.IP "require_all_roles \- require the user to have all roles listed" 4
.IX Item "require_all_roles - require the user to have all roles listed"
.Vb 1
\&    get \*(Aq/foo\*(Aq => require_all_roles [qw(Foo Bar)] => sub { ... };
.Ve
.Sp
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 \s-1URL. \s0 If
they are logged in but do not have all of the specified roles, they will be
redirected to the access denied \s-1URL.\s0
.ie n .SS "Replacing the Default "" /login "" and "" /login/denied "" Routes"
.el .SS "Replacing the Default \f(CW /login \fP and \f(CW /login/denied \fP Routes"
.IX Subsection "Replacing the Default /login and /login/denied Routes"
By default, the plugin adds a route to present a simple login form at that \s-1URL.\s0
If you would rather add your own, set the \f(CW\*(C`no_default_pages\*(C'\fR setting to a true
value, and define your own route which responds to \f(CW\*(C`/login\*(C'\fR with a login page.
Alternatively you can let \s-1DPAE\s0 add the routes and handle the status codes, etc.
and simply define the setting \f(CW\*(C`login_page_handler\*(C'\fR and/or
\&\f(CW\*(C`permission_denied_page_handler\*(C'\fR with the name of a subroutine to be called to
handle the route. Note that it must be a fully qualified sub. E.g.
.PP
.Vb 4
\&    plugins:
\&      Auth::Extensible:
\&        login_page_handler: \*(AqMy::App:login_page_handler\*(Aq
\&        permission_denied_page_handler: \*(AqMy::App:permission_denied_page_handler\*(Aq
.Ve
.PP
Then in your code you might simply use a template:
.PP
.Vb 3
\&    sub permission_denied_page_handler {
\&        template \*(Aqaccount/login\*(Aq;
\&    }
.Ve
.PP
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 \*(L"permission denied\*(R" page
\&\s-1URL,\s0 which defaults to \f(CW\*(C`/login/denied\*(C'\fR but may be changed using the
\&\f(CW\*(C`denied_page\*(C'\fR option.
.PP
Again, by default a route is added to respond to that \s-1URL\s0 with a default page;
again, you can disable this by setting \f(CW\*(C`no_default_pages\*(C'\fR and creating your
own.
.PP
This would still leave the routes \f(CW\*(C`post \*(Aq/login\*(Aq\*(C'\fR and \f(CW\*(C`any \*(Aq/logout\*(Aq\*(C'\fR
routes in place. To disable them too, set the option \f(CW\*(C`no_login_handler\*(C'\fR 
to a true value. In this case, these routes should be defined by the user,
and should do at least the following:
.PP
.Vb 12
\&    post \*(Aq/login\*(Aq => 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 \*(Aq/logout\*(Aq => sub {
\&        session\->destroy;
\&    };
.Ve
.PP
If you want to use the default \f(CW\*(C`post \*(Aq/login\*(Aq\*(C'\fR and \f(CW\*(C`any \*(Aq/logout\*(Aq\*(C'\fR routes
you can configure them. See below.
.SS "Keywords"
.IX Subsection "Keywords"
.IP "require_login" 4
.IX Item "require_login"
Used to wrap a route which requires a user to be logged in order to access
it.
.Sp
.Vb 1
\&    get \*(Aq/secret\*(Aq => require_login sub { .... };
.Ve
.IP "require_role" 4
.IX Item "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.
.Sp
.Vb 1
\&    get \*(Aq/beer\*(Aq => require_role BeerDrinker => sub { ... };
.Ve
.Sp
You can also provide a regular expression, if you need to match the role using a
regex \- for example:
.Sp
.Vb 1
\&    get \*(Aq/beer\*(Aq => require_role qr/Drinker$/ => sub { ... };
.Ve
.IP "require_any_role" 4
.IX Item "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.
.Sp
.Vb 1
\&    get \*(Aq/foo\*(Aq => require_any_role [qw(Foo Bar)] => sub { ... };
.Ve
.IP "require_all_roles" 4
.IX Item "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.
.Sp
.Vb 1
\&    get \*(Aq/foo\*(Aq => require_all_roles [qw(Foo Bar)] => sub { ... };
.Ve
.IP "logged_in_user" 4
.IX Item "logged_in_user"
Returns a hashref of details of the currently logged-in user, if there is one.
.Sp
The details you get back will depend upon the authentication provider in use.
.IP "user_has_role" 4
.IX Item "user_has_role"
Check if a user has the role named.
.Sp
By default, the currently-logged-in user will be checked, so you need only name
the role you're looking for:
.Sp
.Vb 1
\&    if (user_has_role(\*(AqBeerDrinker\*(Aq)) { pour_beer(); }
.Ve
.Sp
You can also provide the username to check;
.Sp
.Vb 1
\&    if (user_has_role($user, $role)) { .... }
.Ve
.IP "user_roles" 4
.IX Item "user_roles"
Returns a list of the roles of a user.
.Sp
By default, roles for the currently-logged-in user will be checked;
alternatively, you may supply a username to check.
.Sp
Returns a list or arrayref depending on context.
.IP "authenticate_user" 4
.IX Item "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.
.Sp
For example:
.Sp
.Vb 3
\&    if (authenticate_user($username, $password)) {
\&        ...
\&    }
.Ve
.Sp
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.
.Sp
In boolean context, returns simply true or false; in list context, returns
\&\f(CW\*(C`($success, $realm)\*(C'\fR.
.SS "\s-1SAMPLE CONFIGURATION\s0"
.IX Subsection "SAMPLE CONFIGURATION"
In your application's configuration file:
.PP
.Vb 9
\&    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 (\*(Aq/\*(Aq is default)
\&            user_home_page: \*(Aq/user\*(Aq
\&            # After /logout: If no return_url is given: land here (no default)
\&            exit_page: \*(Aq/\*(Aq
\&            
\&            # 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: \*(Aqfoo\*(Aq
.Ve
.PP
\&\fBPlease note\fR that you \fBmust\fR 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.
.SH "AUTHOR"
.IX Header "AUTHOR"
David Precious, \f(CW\*(C`<davidp at preshweb.co.uk>\*(C'\fR
.SH "BUGS / FEATURE REQUESTS"
.IX Header "BUGS / FEATURE REQUESTS"
This is an early version; there may still be bugs present or features missing.
.PP
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>
.SH "ACKNOWLEDGEMENTS"
.IX Header "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.
.PP
Configurable login/logout URLs added by Rene (hertell)
.PP
Regex support for require_role by chenryn
.PP
Support for user_roles looking in other realms by Colin Ewen (casao)
.PP
Config options for default login/logout handlers by Henk van Oers (hvoers)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2012\-16 David Precious.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the \s-1GNU\s0 General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See http://dev.perl.org/licenses/ for more information.