.\" 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::Provider::Database 3pm"
.TH Dancer::Plugin::Auth::Extensible::Provider::Database 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::Database \- authenticate via a database
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is an authentication provider designed to authenticate users against
a database, using Dancer::Plugin::Database to access a database.
.PP
Crypt::SaltedHash is used to handle hashed passwords securely; you wouldn't
want to store plain text passwords now, would you?  (If your answer to that is
yes, please reconsider; you really don't want to do that, when it's so easy to
do things right!)
.PP
See Dancer::Plugin::Database for how to configure a database connection
appropriately; see the \*(L"\s-1CONFIGURATION\*(R"\s0 section below for how to configure this
authentication provider with database details.
.PP
See Dancer::Plugin::Auth::Extensible for details on how to use the
authentication framework, including how to pick a more useful authentication
provider.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
This provider tries to use sensible defaults, so you may not need to provide
much configuration if your database tables look similar to those in the
\&\*(L"\s-1SUGGESTED SCHEMA\*(R"\s0 section below.
.PP
The most basic configuration, assuming defaults for all options, and defining a
single authentication realm named 'users':
.PP
.Vb 5
\&    plugins:
\&        Auth::Extensible:
\&            realms:
\&                users:
\&                    provider: \*(AqDatabase\*(Aq
.Ve
.PP
You would still need to have provided suitable database connection details to
Dancer::Plugin::Database, of course;  see the docs for that plugin for full
details, but it could be as simple as, e.g.:
.PP
.Vb 8
\&    plugins:
\&        Auth::Extensible:
\&            realms:
\&                users:
\&                    provider: \*(AqDatabase\*(Aq
\&        Database:
\&            driver: \*(AqSQLite\*(Aq
\&            database: \*(Aqtest.sqlite\*(Aq
.Ve
.PP
A full example showing all options:
.PP
.Vb 8
\&    plugins:
\&        Auth::Extensible:
\&            realms:
\&                users:
\&                    provider: \*(AqDatabase\*(Aq
\&                    # optionally set DB connection name to use (see named 
\&                    # connections in Dancer::Plugin::Database docs)
\&                    db_connection_name: \*(Aqfoo\*(Aq
\&
\&                    # Optionally disable roles support, if you only want to check
\&                    # for successful logins but don\*(Aqt need to use role\-based access:
\&                    disable_roles: 1
\&
\&                    # optionally specify names of tables if they\*(Aqre not the defaults
\&                    # (defaults are \*(Aqusers\*(Aq, \*(Aqroles\*(Aq and \*(Aquser_roles\*(Aq)
\&                    users_table: \*(Aqusers\*(Aq
\&                    roles_table: \*(Aqroles\*(Aq
\&                    user_roles_table: \*(Aquser_roles\*(Aq
\&
\&                    # optionally set the column names (see the SUGGESTED SCHEMA
\&                    # section below for the default names; if you use them, they\*(Aqll
\&                    # Just Work)
\&                    users_id_column: \*(Aqid\*(Aq
\&                    users_username_column: \*(Aqusername\*(Aq
\&                    users_password_column: \*(Aqpassword\*(Aq
\&                    roles_id_column: \*(Aqid\*(Aq
\&                    roles_role_column: \*(Aqrole\*(Aq
\&                    user_roles_user_id_column: \*(Aquser_id\*(Aq
\&                    user_roles_role_id_column: \*(Aqroles_id\*(Aq
.Ve
.PP
See the main Dancer::Plugin::Auth::Extensible documentation for how to
configure multiple authentication realms.
.SH "SUGGESTED SCHEMA"
.IX Header "SUGGESTED SCHEMA"
If you use a schema similar to the examples provided here, you should need
minimal configuration to get this authentication provider to work for you.
.PP
The examples given here should be MySQL-compatible; minimal changes should be
required to use them with other database engines.
.SS "users table"
.IX Subsection "users table"
You'll need a table to store user accounts in, of course.  A suggestion is
something like:
.PP
.Vb 5
\&    CREATE TABLE users (
\&        id       INTEGER     AUTO_INCREMENT PRIMARY KEY,
\&        username VARCHAR(32) NOT NULL       UNIQUE KEY,
\&        password VARCHAR(40) NOT NULL
\&    );
.Ve
.PP
You will quite likely want other fields to store e.g. the user's name, email
address, etc; all columns from the users table will be returned by the
\&\f(CW\*(C`logged_in_user\*(C'\fR keyword for your convenience.
.SS "roles table"
.IX Subsection "roles table"
You'll need a table to store a list of available roles in (unless you're not
using roles \- in which case, disable role support (see the \*(L"\s-1CONFIGURATION\*(R"\s0
section).
.PP
.Vb 4
\&    CREATE TABLE roles (
\&        id    INTEGER     AUTO_INCREMENT PRIMARY KEY,
\&        role  VARCHAR(32) NOT NULL
\&    );
.Ve
.SS "user_roles table"
.IX Subsection "user_roles table"
Finally, (unless you've disabled role support)  you'll need a table to store
user <\-> role mappings (i.e. one row for every role a user has; so adding 
extra roles to a user consists of adding a new role to this table).  It's 
entirely up to you whether you use an \*(L"id\*(R" column in this table; you probably
shouldn't need it.
.PP
.Vb 5
\&    CREATE TABLE user_roles (
\&        user_id  INTEGER  NOT NULL,
\&        role_id  INTEGER  NOT NULL,
\&        UNIQUE KEY user_role (user_id, role_id)
\&    );
.Ve
.PP
If you're using InnoDB tables rather than the default MyISAM, you could add a
foreign key constraint for better data integrity; see the MySQL documentation
for details, but a table definition using foreign keys could look like:
.PP
.Vb 5
\&    CREATE TABLE user_roles (
\&        user_id  INTEGER, FOREIGN KEY (user_id) REFERENCES users (id),
\&        role_id  INTEGER, FOREIGN_KEY (role_id) REFERENCES roles (id),
\&        UNIQUE KEY user_role (user_id, role_id)
\&    ) ENGINE=InnoDB;
.Ve