1NAME
2    Dancer2::Plugin::Auth::Extensible::Provider::DBIC - authenticate via the
3    Dancer2::Plugin::DBIC plugin
4
5DESCRIPTION
6    This class is an authentication provider designed to authenticate users
7    against a database, using Dancer2::Plugin::DBIC to access a database.
8
9    See Dancer2::Plugin::DBIC for how to configure a database connection
10    appropriately; see the "CONFIGURATION" section below for how to
11    configure this authentication provider with database details.
12
13    See Dancer2::Plugin::Auth::Extensible for details on how to use the
14    authentication framework.
15
16CONFIGURATION
17    This provider tries to use sensible defaults, in the same manner as
18    Dancer2::Plugin::Auth::Extensible::Provider::Database, so you may not
19    need to provide much configuration if your database tables look similar
20    to those.
21
22    The most basic configuration, assuming defaults for all options, and
23    defining a single authentication realm named 'users':
24
25        plugins:
26            Auth::Extensible:
27                realms:
28                    users:
29                        provider: 'DBIC'
30
31    You would still need to have provided suitable database connection
32    details to Dancer2::Plugin::DBIC, of course; see the docs for that
33    plugin for full details, but it could be as simple as, e.g.:
34
35        plugins:
36            Auth::Extensible:
37                realms:
38                    users:
39                        provider: 'DBIC'
40                        users_resultset: 'User'
41                        roles_resultset: Role
42                        user_roles_resultset: UserRole
43            DBIC:
44                default:
45                    dsn: dbi:mysql:database=mydb;host=localhost
46                    schema_class: MyApp::Schema
47                    user: user
48                    pass: secret
49
50    A full example showing all options:
51
52        plugins:
53            Auth::Extensible:
54                realms:
55                    users:
56                        provider: 'DBIC'
57
58                        # Should get_user_details return an inflated DBIC row
59                        # object? Defaults to false which will return a hashref
60                        # inflated using DBIx::Class::ResultClass::HashRefInflator
61                        # instead. This also affects what `logged_in_user` returns.
62                        user_as_object: 1
63
64                        # Optionally specify the sources of the data if not the
65                        # defaults (as shown).  See notes below for how these
66                        # generate the resultset names.  If you use standard DBIC
67                        # resultset names, then these and the column names are the
68                        # only settings you might need.  The relationships between
69                        # these resultsets is automatically introspected by
70                        # inspection of the schema.
71                        users_source: 'user'
72                        roles_source: 'role'
73                        user_roles_source: 'user_role'
74
75                        # optionally set the column names
76                        users_username_column: username
77                        users_password_column: password
78                        roles_role_column: role
79
80                        # This plugin supports the DPAE record_lastlogin functionality.
81                        # Optionally set the column name:
82                        users_lastlogin_column: lastlogin
83
84                        # Optionally set columns for user_password functionality in
85                        # Dancer2::Plugin::Auth::Extensible
86                        users_pwresetcode_column: pw_reset_code
87                        users_pwchanged_column:   # Time of reset column. No default.
88
89                        # Days after which passwords expire. See logged_in_user_password_expired
90                        # functionality in Dancer2::Plugin::Auth::Extensible
91                        password_expiry_days:       # No default
92
93                        # Optionally set the name of the DBIC schema
94                        schema_name: myschema
95
96                        # Optionally set additional conditions when searching for the
97                        # user in the database. These are the same format as required
98                        # by DBIC, and are passed directly to the DBIC resultset search
99                        user_valid_conditions:
100                            deleted: 0
101                            account_request:
102                                "<": 1
103
104                        # Optionally specify a key for the user's roles to be returned in.
105                        # Roles will be returned as role_name => 1 hashref pairs
106                        roles_key: roles
107
108                        # Optionally specify the algorithm when encrypting new passwords
109                        encryption_algorithm: SHA-512
110
111                        # If you don't use standard DBIC resultset names, you might
112                        # need to configure these instead:
113                        users_resultset: User
114                        roles_resultset: Role
115                        user_roles_resultset: UserRole
116
117                        # Optional: To validate passwords using a method called
118                        # 'check_password' in users_resultset result class
119                        # which takes the password to check as a single argument:
120                        users_password_check: check_password
121
122                        # Deprecated settings. The following settings were renamed for clarity
123                        # to the *_source settings
124                        users_table:
125                        roles_table:
126                        user_roles_table:
127
128    user_as_object
129        Defaults to false.
130
131        By default a row object is returned as a simple hash reference using
132        DBIx::Class::ResultClass::HashRefInflator. Setting this to true
133        causes normal row objects to be returned instead.
134
135    user_source
136        Specifies the source name that contains the users. This will be
137        camelized to generate the resultset name. The relationship to
138        user_roles_source will be introspected from the schema.
139
140    role_source
141        Specifies the source name that contains the roles. This will be
142        camelized to generate the resultset name. The relationship to
143        user_roles_source will be introspected from the schema.
144
145    user_roles_source
146        Specifies the source name that contains the user_roles joining
147        table. This will be camelized to generate the resultset name. The
148        relationship to the user and role source will be introspected from
149        the schema.
150
151    users_username_column
152        Specifies the column name of the username column in the users table
153
154    users_password_column
155        Specifies the column name of the password column in the users table
156
157    roles_role_column
158        Specifies the column name of the role name column in the roles table
159
160    schema_name
161        Specfies the name of the Dancer2::Plugin::DBIC schema to use. If not
162        specified, will default in the same manner as the DBIC plugin.
163
164    user_valid_conditions
165        Specifies additional search parameters when looking up a user in the
166        users table. For example, you might want to exclude any account this
167        is flagged as deleted or disabled.
168
169        The value of this parameter will be passed directly to DBIC as a
170        search condition. It is therefore possible to nest parameters and
171        use different operators for the condition. See the example config
172        above for an example.
173
174    roles_key
175        Specifies a key for the returned user hash to also return the user's
176        roles in. The value of this key will contain a hash ref, which will
177        contain each permission with a value of 1. In your code you might
178        then have:
179
180            my $user = logged_in_user;
181            return foo_bar($user);
182
183            sub foo_bar
184            {   my $user = shift;
185                if ($user->{roles}->{beer_drinker}) {
186                   ...
187                }
188            }
189
190        This isn't intended to replace the "user_has_role" in
191        Dancer2::Plugin::Auth::Extensible keyword. Instead it is intended to
192        make it easier to access a user's roles if the user hash is being
193        passed around (without requiring access to the user_has_role keyword
194        in other modules).
195
196    users_resultset
197    roles_resultset
198    user_roles_resultset
199        These configuration values are provided for fine-grain tuning of
200        your DBIC resultset names. If you use standard DBIC naming
201        practices, you will not need to configure these, and they will be
202        generated internally automatically.
203
204SUGGESTED SCHEMA
205    If you use a schema similar to the examples provided here, you should
206    need minimal configuration to get this authentication provider to work
207    for you. The examples given here should be MySQL-compatible; minimal
208    changes should be required to use them with other database engines.
209
210  user Table
211    You'll need a table to store user accounts in, of course. A suggestion
212    is something like:
213
214         CREATE TABLE user (
215             id int(11) NOT NULL AUTO_INCREMENT,
216                     username varchar(32) NOT NULL,
217             password varchar(40) DEFAULT NULL,
218             name varchar(128) DEFAULT NULL,
219             email varchar(255) DEFAULT NULL,
220             deleted tinyint(1) NOT NULL DEFAULT '0',
221             lastlogin datetime DEFAULT NULL,
222             pw_changed datetime DEFAULT NULL,
223             pw_reset_code varchar(255) DEFAULT NULL,
224             PRIMARY KEY (id)
225         );
226
227    All columns from the users table will be returned by the
228    "logged_in_user" keyword for your convenience.
229
230  role Table
231    You'll need a table to store a list of available groups in.
232
233             CREATE TABLE role (
234             id int(11) NOT NULL AUTO_INCREMENT,
235             role varchar(32) NOT NULL,
236             PRIMARY KEY (id)
237         );
238
239  user_role Table
240    Also requred is a table mapping the users to the roles.
241
242         CREATE TABLE user_role (
243             user_id int(11) NOT NULL,
244             role_id int(11) NOT NULL,
245             PRIMARY KEY (user_id, role_id),
246             FOREIGN KEY (user_id) REFERENCES user(id),
247             FOREIGN KEY (role_id) REFERENCES role(id)
248         );
249
250SEE ALSO
251    Dancer2::Plugin::Auth::Extensible
252
253    Dancer2::Plugin::DBIC
254
255    Dancer2::Plugin::Auth::Extensible::Provider::Database
256
257AUTHORS
258    Andrew Beverley "<a.beverley@ctrlo.com>"
259
260    Rewrite for Plugin2:
261
262    Peter Mottram, "<peter@sysnix.com>"
263
264CONTRIBUTORS
265    Ben Kaufman (whosgonna)
266
267LICENSE AND COPYRIGHT
268    Copyright 2015-2016 Andrew Beverley
269
270    This program is free software; you can redistribute it and/or modify it
271    under the terms of either: the GNU General Public License as published
272    by the Free Software Foundation; or the Artistic License.
273
274    See http://dev.perl.org/licenses/ for more information.
275
276