1NAME 2 Dancer2::Plugin::Auth::Extensible::Provider::Usergroup - authenticate as 3 a member of a group 4 5SYNOPSIS 6 Define that a user must be logged in and have the proper permissions to 7 access a route: 8 9 get '/unsubscribe' => require_role forum => sub { ... }; 10 11DESCRIPTION 12 This class is an authentication provider designed to authenticate users 13 against a DBIC schema, using Dancer2::Plugin::DBIC to access a database. 14 15 Dancer2::Plugin::Passphrase is used to handle hashed passwords securely; 16 you wouldn't want to store plain text passwords now, would you? (If your 17 answer to that is yes, please reconsider; you really don't want to do 18 that, when it's so easy to do things right!) 19 20 See Dancer2::Plugin::DBIC for how to configure a database connection 21 appropriately; see the "CONFIGURATION" section below for how to 22 configure this authentication provider with database details. 23 24 See Dancer2::Plugin::Auth::Extensible for details on how to use the 25 authentication framework, including how to use "require_login" and 26 "require_role". 27 28CONFIGURATION 29 This provider tries to use sensible defaults, so you may not need to 30 provide much configuration if your database tables look similar to those 31 in the "SUGGESTED SCHEMA" section below. 32 33 The most basic configuration, assuming defaults for all options, and 34 defining a single authentication realm named 'usergroup': 35 36 plugins: 37 Auth::Extensible: 38 realms: 39 usergroup: 40 provider: 'Usergroup' 41 42 You would still need to have provided suitable database connection 43 details to Dancer2::Plugin::DBIC, of course; see the docs for that 44 plugin for full details, but it could be as simple as, e.g.: 45 46 plugins: 47 Auth::Extensible: 48 realms: 49 usergroup: 50 provider: 'Usergroup' 51 schema_name: 'usergroup' 52 DBIC: 53 usergroup: 54 chema_class: Usergroup::Schema 55 dsn: "dbi:SQLite:dbname=/path/to/usergroup.db" 56 57 A full example showing all options: 58 59 plugins: 60 Auth::Extensible: 61 realms: 62 usergroup: 63 provider: 'Usergroup' 64 65 # optional schema name for DBIC (default 'default') 66 schema_name: 'usergroup' 67 68 # optionally specify names of result sets if they're not the defaults 69 # (defaults are 'User' and 'Role') 70 user_rset: 'User' 71 user_role_rset: 'Role' 72 73 # optionally set the column names (see the SUGGESTED SCHEMA 74 # section below for the default names; if you use them, they'll 75 # Just Work) 76 user_login_name_column: 'login_name' 77 user_passphrase_column: 'passphrase' 78 user_role_column: 'role' 79 80 # optionally set a column name that makes a user useable 81 # (not all login names can be used to login) 82 user_activated_column: 'activated' 83 84 See the main Dancer2::Plugin::Auth::Extensible documentation for how to 85 configure multiple authentication realms. 86 87ATTRIBUTES 88 schema_name 89 Defaults to 'default', 90 91 schema 92 Defaults to a DBIC schema using "schema_name". 93 94 user_rset 95 The name of the DBIC result class for the user table. 96 97 Defaults to 'User'. 98 99 user_role_rset 100 The name of the DBIC result class for the role view. 101 102 Defaults to 'Role'. 103 104 user_login_name_column 105 The login_name column in "user_rset". 106 107 Defaults to 'login_name'. 108 109 user_passphrase_column 110 The passphrase column in "user_rset". 111 112 Defaults to 'passphrase'. 113 114 user_role_column 115 The role column in "user_role_rset". 116 117 Defaults to 'role'. 118 119 user_activated_column 120 The user activated column in "user_rset". 121 122 Defaults to 'activated'. 123 124SUGGESTED SCHEMA 125 If you use a schema similar to the examples provided here, you should 126 need minimal configuration to get this authentication provider to work 127 for you. 128 129 The examples given here should be SQLite-compatible; minimal changes 130 should be required to use them with other database engines. 131 132 user table 133 You'll need a table to store user accounts in, of course. A suggestion 134 is something like: 135 136 CREATE TABLE users ( 137 id INTEGER PRIMARY KEY, 138 login_name TEXT UNIQUE NOT NULL, 139 passphrase TEXT NOT NULL, 140 activated INTEGER 141 ); 142 143 You will quite likely want other fields to store e.g. the user's name, 144 email address, etc; all columns from the users table will be returned by 145 the "logged_in_user" keyword for your convenience. 146 147 group table 148 You'll need a table to store a list of available groups in. 149 150 CREATE TABLE groups ( 151 id INTEGER PRIMARY KEY, 152 group_name TEXT UNIQUE NOT NULL 153 ); 154 155 membership table 156 To make users a member you'll need a table to store user <-> group 157 mappings. 158 159 CREATE TABLE memberships ( 160 id INTEGER PRIMARY KEY, 161 user_id INTEGER NOT NULL REFERENCES users (id), 162 group_id INTEGER NOT NULL REFERENCES groups (id) 163 ); 164 165 role view 166 Map the user role by name. 167 168 CREATE VIEW roles AS 169 SELECT login_name, group_name AS role 170 FROM users 171 LEFT JOIN memberships ON users.id = memberships.user_id 172 LEFT JOIN groups ON groups.id = memberships.group_id 173 ; 174 175 indexes 176 You want your data quickly. 177 178 CREATE UNIQUE INDEX login_name ON users (login_name); 179 CREATE UNIQUE INDEX group_name ON groups (group_name); 180 CREATE UNIQUE INDEX user_group ON memberships (user_id, group_id); 181 CREATE INDEX member_user ON memberships (user_id); 182 CREATE INDEX member_group ON memberships (group_id); 183 184INTERNALS 185 get_user_details 186 Used by Dancer2::Plugin::Auth::Extensible 187 188 match_password 189 Used by Dancer2::Plugin::Auth::Extensible 190 191 authenticate_user 192 Used by Dancer2::Plugin::Auth::Extensible 193 194 get_user_roles 195 Used by Dancer2::Plugin::Auth::Extensible 196 197COPYRIGHT 198 Copyright (c) 2014 Henk van Oers 199 200LICENSE 201 This library is free software and may be distributed under the same 202 terms as perl itself. 203 204