1NAME
2 Dancer::Plugin::Auth::Extensible - extensible authentication framework
3 for Dancer apps
4
5DESCRIPTION
6 A user authentication and authorisation framework plugin for Dancer
7 apps.
8
9 Makes it easy to require a user to be logged in to access certain
10 routes, provides role-based access control, and supports various
11 authentication methods/sources (config file, database, Unix system
12 users, etc).
13
14 Designed to support multiple authentication realms and to be as
15 extensible as possible, and to make secure password handling easy. The
16 base class for auth providers makes handling `RFC2307'-style hashed
17 passwords really simple, so you have no excuse for storing plain-text
18 passwords. A simple script to generate RFC2307-style hashed passwords is
19 included, or you can use Crypt::SaltedHash yourself to do so, or use the
20 `slappasswd' utility if you have it installed.
21
22SYNOPSIS
23 Configure the plugin to use the authentication provider class you wish
24 to use:
25
26 plugins:
27 Auth::Extensible:
28 realms:
29 users:
30 provider: Example
31 ....
32
33 The configuration you provide will depend on the authentication provider
34 module in use. For a simple example, see
35 Dancer::Plugin::Auth::Extensible::Provider::Config.
36
37 Define that a user must be logged in and have the proper permissions to
38 access a route:
39
40 get '/secret' => require_role Confidant => sub { tell_secrets(); };
41
42 Define that a user must be logged in to access a route - and find out
43 who is logged in with the `logged_in_user' keyword:
44
45 get '/users' => require_login sub {
46 my $user = logged_in_user;
47 return "Hi there, $user->{username}";
48 };
49
50AUTHENTICATION PROVIDERS
51 For flexibility, this authentication framework uses simple
52 authentication provider classes, which implement a simple interface and
53 do whatever is required to authenticate a user against the chosen source
54 of authentication.
55
56 For an example of how simple provider classes are, so you can build your
57 own if required or just try out this authentication framework plugin
58 easily, see Dancer::Plugin::Auth::Extensible::Provider::Example.
59
60 This framework supplies the following providers out-of-the-box:
61
62 Dancer::Plugin::Auth::Extensible::Provider::Unix
63 Authenticates users using system accounts on Linux/Unix type boxes
64
65 Dancer::Plugin::Auth::Extensible::Provider::Database
66 Authenticates users stored in a database table
67
68 Dancer::Plugin::Auth::Extensible::Provider::Config
69 Authenticates users stored in the app's config
70
71 Need to write your own? Just subclass
72 Dancer::Plugin::Auth::Extensible::Provider::Base and implement the
73 required methods, and you're good to go!
74
75CONTROLLING ACCESS TO ROUTES
76 Keywords are provided to check if a user is logged in / has appropriate
77 roles.
78
79 require_login - require the user to be logged in
80 get '/dashboard' => require_login sub { .... };
81
82 If the user is not logged in, they will be redirected to the login
83 page URL to log in. The default URL is `/login' - this may be
84 changed with the `login_page' option.
85
86 require_role - require the user to have a specified role
87 get '/beer' => require_role BeerDrinker => sub { ... };
88
89 Requires that the user be logged in as a user who has the specified
90 role. If the user is not logged in, they will be redirected to the
91 login page URL. If they are logged in, but do not have the required
92 role, they will be redirected to the access denied URL.
93
94 require_any_roles - require the user to have one of a list of roles
95 get '/drink' => require_any_role [qw(BeerDrinker VodaDrinker)] => sub {
96 ...
97 };
98
99 Requires that the user be logged in as a user who has any one (or
100 more) of the roles listed. If the user is not logged in, they will
101 be redirected to the login page URL. If they are logged in, but do
102 not have any of the specified roles, they will be redirected to the
103 access denied URL.
104
105 require_all_roles - require the user to have all roles listed
106 get '/foo' => require_all_roles [qw(Foo Bar)] => sub { ... };
107
108 Requires that the user be logged in as a user who has all of the
109 roles listed. If the user is not logged in, they will be redirected
110 to the login page URL. If they are logged in but do not have all of
111 the specified roles, they will be redirected to the access denied
112 URL.
113
114 Replacing the Default ` /login ' and ` /login/denied ' Routes
115 By default, the plugin adds a route to present a simple login form at
116 that URL. If you would rather add your own, set the `no_default_pages'
117 setting to a true value, and define your own route which responds to
118 `/login' with a login page. Alternatively you can let DPAE add the
119 routes and handle the status codes, etc. and simply define the setting
120 `login_page_handler' and/or `permission_denied_page_handler' with the
121 name of a subroutine to be called to handle the route. Note that it must
122 be a fully qualified sub. E.g.
123
124 plugins:
125 Auth::Extensible:
126 login_page_handler: 'My::App:login_page_handler'
127 permission_denied_page_handler: 'My::App:permission_denied_page_handler'
128
129 Then in your code you might simply use a template:
130
131 sub permission_denied_page_handler {
132 template 'account/login';
133 }
134
135 If the user is logged in, but tries to access a route which requires a
136 specific role they don't have, they will be redirected to the
137 "permission denied" page URL, which defaults to `/login/denied' but may
138 be changed using the `denied_page' option.
139
140 Again, by default a route is added to respond to that URL with a default
141 page; again, you can disable this by setting `no_default_pages' and
142 creating your own.
143
144 This would still leave the routes `post '/login'' and `any '/logout''
145 routes in place. To disable them too, set the option `no_login_handler'
146 to a true value. In this case, these routes should be defined by the
147 user, and should do at least the following:
148
149 post '/login' => sub {
150 my ($success, $realm) = authenticate_user(
151 params->{username}, params->{password}
152 );
153 if ($success) {
154 session logged_in_user => params->{username};
155 session logged_in_user_realm => $realm;
156 # other code here
157 } else {
158 # authentication failed
159 }
160 };
161
162 any '/logout' => sub {
163 session->destroy;
164 };
165
166 If you want to use the default `post '/login'' and `any '/logout''
167 routes you can configure them. See below.
168
169 Keywords
170 require_login
171 Used to wrap a route which requires a user to be logged in order to
172 access it.
173
174 get '/secret' => require_login sub { .... };
175
176 require_role
177 Used to wrap a route which requires a user to be logged in as a user
178 with the specified role in order to access it.
179
180 get '/beer' => require_role BeerDrinker => sub { ... };
181
182 You can also provide a regular expression, if you need to match the
183 role using a regex - for example:
184
185 get '/beer' => require_role qr/Drinker$/ => sub { ... };
186
187 require_any_role
188 Used to wrap a route which requires a user to be logged in as a user
189 with any one (or more) of the specified roles in order to access it.
190
191 get '/foo' => require_any_role [qw(Foo Bar)] => sub { ... };
192
193 require_all_roles
194 Used to wrap a route which requires a user to be logged in as a user
195 with all of the roles listed in order to access it.
196
197 get '/foo' => require_all_roles [qw(Foo Bar)] => sub { ... };
198
199 logged_in_user
200 Returns a hashref of details of the currently logged-in user, if
201 there is one.
202
203 The details you get back will depend upon the authentication
204 provider in use.
205
206 user_has_role
207 Check if a user has the role named.
208
209 By default, the currently-logged-in user will be checked, so you
210 need only name the role you're looking for:
211
212 if (user_has_role('BeerDrinker')) { pour_beer(); }
213
214 You can also provide the username to check;
215
216 if (user_has_role($user, $role)) { .... }
217
218 user_roles
219 Returns a list of the roles of a user.
220
221 By default, roles for the currently-logged-in user will be checked;
222 alternatively, you may supply a username to check.
223
224 Returns a list or arrayref depending on context.
225
226 authenticate_user
227 Usually you'll want to let the built-in login handling code deal
228 with authenticating users, but in case you need to do it yourself,
229 this keyword accepts a username and password, and optionally a
230 specific realm, and checks whether the username and password are
231 valid.
232
233 For example:
234
235 if (authenticate_user($username, $password)) {
236 ...
237 }
238
239 If you are using multiple authentication realms, by default each
240 realm will be consulted in turn. If you only wish to check one of
241 them (for instance, you're authenticating an admin user, and there's
242 only one realm which applies to them), you can supply the realm as
243 an optional third parameter.
244
245 In boolean context, returns simply true or false; in list context,
246 returns `($success, $realm)'.
247
248 SAMPLE CONFIGURATION
249 In your application's configuation file:
250
251 session: simple
252 plugins:
253 Auth::Extensible:
254 # Set to 1 if you want to disable the use of roles (0 is default)
255 disable_roles: 0
256 # After /login: If no return_url is given: land here ('/' is default)
257 user_home_page: '/user'
258 # After /logout: If no return_url is given: land here (no default)
259 exit_page: '/'
260
261 # List each authentication realm, with the provider to use and the
262 # provider-specific settings (see the documentation for the provider
263 # you wish to use)
264 realms:
265 realm_one:
266 provider: Database
267 db_connection_name: 'foo'
268
269 Please note that you must have a session provider configured. The
270 authentication framework requires sessions in order to track information
271 about the currently logged in user. Please see Dancer::Session for
272 information on how to configure session management within your
273 application.
274
275AUTHOR
276 David Precious, `<davidp at preshweb.co.uk>'
277
278BUGS / FEATURE REQUESTS
279 This is an early version; there may still be bugs present or features
280 missing.
281
282 This is developed on GitHub - please feel free to raise issues or pull
283 requests against the repo at:
284 https://github.com/bigpresh/Dancer-Plugin-Auth-Extensible
285
286ACKNOWLEDGEMENTS
287 Valuable feedback on the early design of this module came from many
288 people, including Matt S Trout (mst), David Golden (xdg), Damien
289 Krotkine (dams), Daniel Perrett, and others.
290
291 Configurable login/logout URLs added by Rene (hertell)
292
293 Regex support for require_role by chenryn
294
295 Support for user_roles looking in other realms by Colin Ewen (casao)
296
297 Config options for default login/logout handlers by Henk van Oers
298 (hvoers)
299
300LICENSE AND COPYRIGHT
301 Copyright 2012-16 David Precious.
302
303 This program is free software; you can redistribute it and/or modify it
304 under the terms of either: the GNU General Public License as published
305 by the Free Software Foundation; or the Artistic License.
306
307 See http://dev.perl.org/licenses/ for more information.
308
309