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