README
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