1CGI::Ex::Auth(3) User Contributed Perl Documentation CGI::Ex::Auth(3)
2
6 CGI::Ex::Auth - Handle logins nicely.
7
9 use CGI::Ex::Auth;
10 ### authorize the user
12 my $auth = CGI::Ex::Auth->get_valid_auth({
13 get_pass_by_user => \&get_pass_by_user,
14 });
15 sub get_pass_by_user {
17 my $auth = shift;
18 my $user = shift;
19 my $pass = some_way_of_getting_password($user);
20 return $pass;
21 }
22 ### OR - if you are using a OO based CGI or Application
24 sub require_authentication {
26 my $self = shift;
27 return $self->{'auth'} = CGI::Ex::Auth->get_valid_auth({
29 get_pass_by_user => sub {
30 my ($auth, $user) = @_;
31 return $self->get_pass($user);
32 },
33 });
34 }
35 sub get_pass {
37 my ($self, $user) = @_;
38 return $self->loopup_and_cache_pass($user);
39 }
40
42 CGI::Ex::Auth allows for auto-expiring, safe and easy web based logins.
43 Auth uses javascript modules that perform MD5 hashing to cram the pass‐
44 word on the client side before passing them through the internet.
45 For the stored cookie you can choose to use simple cram mechanisms,
47 secure hash cram tokens, auto expiring logins (not cookie based), and
48 Crypt::Blowfish protection. You can also choose to keep passwords
49 plaintext and to use perl's crypt for testing passwords.
50 A downside to this module is that it does not use a session to preserve
52 state so get_pass_by_user has to happen on every request (any authenti‐
53 cated area has to verify authentication each time). A plus is that you
54 don't need to use a session if you don't want to. It is up to the
55 interested reader to add caching to the get_pass_by_user method.
56
58 "new"
59 Constructor. Takes a hashref of properties as arguments.
60 Many of the methods which may be overridden in a subclass, or may
62 be passed as properties to the new constuctor such as in the fol‐
63 lowing:
64 CGI::Ex::Auth->new({
66 get_pass_by_user => \&my_pass_sub,
67 key_user => 'my_user',
68 key_pass => 'my_pass',
69 login_header => \"<h1>My Login</h1>",
70 });
71 The following methods will look for properties of the same name.
73 Each of these will be described separately.
74 cgix
76 cleanup_user
77 cookies
78 expires_min
79 form
80 form_name
81 get_pass_by_user
82 js_uri_path
83 key_cookie
84 key_expires_min
85 key_logout
86 key_pass
87 key_redirect
88 key_save
89 key_time
90 key_user
91 key_verify
92 key_loggedout
93 bounce_on_logout
94 login_footer
95 login_form
96 login_header
97 login_script
98 login_template
99 handle_success
100 handle_failure
101 success_hook
102 failure_hook
103 logout_hook
104 no_cookie_verify
105 path_info
106 script_name
107 secure_hash_keys
108 template_args
109 template_include_path
110 text_user
111 text_pass
112 text_save
113 text_submit
114 hide_save
115 use_base64
116 use_blowfish
117 use_crypt
118 use_plaintext
119 verify_payload
120 verify_user
121 "generate_token"
123 Takes either an auth_data object from a auth_data returned by ver‐
124 ify_token, or a hashref of arguments.
125 Possible arguments are:
127 user - the username we are generating the token for
129 real_pass - the password of the user (if use_plaintext is false
130 and use_crypt is false, the password can be an md5sum
131 of the user's password)
132 use_blowfish - indicates that we should use Crypt::Blowfish to protect
133 the generated token. The value of this argument is used
134 as the key. Default is false.
135 use_base64 - indicates that we should use Base64 encoding to protect
136 the generated token. Default is true. Will not be
137 used if use_blowfish is true.
138 use_plaintext - indicates that we should keep the password in plaintext
139 use_crypt - also indicates that we should keep the password in plaintext
140 expires_min - says how many minutes until the generated token expires.
141 Values <= 0 indicate to not ever expire. Used only on cram
142 types.
143 payload - a payload that will be passed to generate_payload and then
144 will be added to cram type tokens. It cannot contain a /.
145 prefer_simple_cram
146 - If the secure_hash_keys method returns keys, and it is a non-plaintext
147 token, generate_token will create a secure_hash_cram. Set
148 this value to true to tell it to use a simple_cram. This
149 is generally only useful in testing.
150 The following are types of tokens that can be generated by gener‐
152 ate_token. Each type includes pseudocode and a sample of a gener‐
153 ated that token.
154 plaintext:
156 user := "paul"
157 real_pass := "123qwe"
158 token := join("/", user, real_pass);
159 use_base64 := 0
161 token == "paul/123qwe"
162 use_base64 := 1
164 token == "cGF1bC8xMjNxd2U="
165 use_blowfish := "foobarbaz"
167 token == "6da702975190f0fe98a746f0d6514683"
168 Notes: This token will be used if either use_plaintext or use_crypt is set.
170 The real_pass can also be the md5_sum of the password. If real_pass is an md5_sum
171 of the password but the get_pass_by_user hook returns the crypt'ed password, the
172 token will not be able to be verified.
173 simple_cram:
175 user := "paul"
176 real_pass := "123qwe"
177 server_time := 1148512991 # a time in seconds since epoch
178 expires_min := 6 * 60
179 payload := "something"
180 md5_pass := md5_sum(real_pass) # if it isn't already a 32 digit md5 sum
182 str := join("/", user, server_time, expires_min, payload, md5_pass)
183 md5_str := md5(sum_str)
184 token := join("/", user, server_time, expires_min, payload, md5_str)
185 use_base64 := 0
187 token == "paul/1148512991/360/something/16d0ba369a4c9781b5981eb89224ce30"
188 use_base64 := 1
190 token == "cGF1bC8xMTQ4NTEyOTkxLzM2MC9zb21ldGhpbmcvMTZkMGJhMzY5YTRjOTc4MWI1OTgxZWI4OTIyNGNlMzA="
191 Notes: use_blowfish is available as well
193 secure_hash_cram:
195 user := "paul"
196 real_pass := "123qwe"
197 server_time := 1148514034 # a time in seconds since epoch
198 expires_min := 6 * 60
199 payload := "something"
200 secure_hash := ["aaaa", "bbbb", "cccc", "dddd"]
201 rand1 := 3 # int(rand(length(secure_hash)))
202 rand2 := 39163 # int(rand(100000))
203 md5_pass := md5_sum(real_pass) # if it isn't already a 32 digit md5 sum
205 sh_str1 := join(".", "sh", secure_hash[rand1], rand2)
207 sh_str2 := join(".", "sh", rand1, rand2)
208 str := join("/", user, server_time, expires_min, payload, md5_pass, sh_str1)
209 md5_str := md5(sum_str)
210 token := join("/", user, server_time, expires_min, payload, md5_str, sh_str2)
211 use_base64 := 0
213 token == "paul/1148514034/360/something/06db2914c9fd4e11499e0652bcf67dae/sh.3.39163"
214 Notes: use_blowfish is available as well. The secure_hash keys need to be set in the
216 "secure_hash_keys" property of the CGI::Ex::Auth object.
217 "get_valid_auth"
219 Performs the core logic. Returns an auth object on successful
220 login. Returns false on errored login (with the details of the
221 error stored in $@). If a false value is returned, execution of
222 the CGI should be halted. get_valid_auth WILL NOT automatically
223 stop execution.
224 $auth->get_valid_auth ⎪⎪ exit;
226 Optionally, the class and a list of arguments may be passed. This
228 will create a new object using the passed arguments, and then run
229 get_valid_auth.
230 CGI::Ex::Auth->get_valid_auth({key_user => 'my_user'}) ⎪⎪ exit;
232 "check_valid_auth"
234 Runs get_valid_auth with login_print and location_bounce set to do
235 nothing. This allows for obtaining login data without forcing an
236 html login page to appear.
237 "login_print"
239 Called if login errored. Defaults to printing a very basic (but
240 adequate) page loaded from login_template..
241 You will want to override it with a template from your own system.
243 The hook that is called will be passed the step to print (currently
244 only "get_login_info" and "no_cookies"), and a hash containing the
245 form variables as well as the following:
246 "login_hash_common"
248 Passed to the template swapped during login_print.
249 %$form, # any keys passed to the login script
251 error # The text "Login Failed" if a login occurred
252 login_data # A login data object if they failed authentication.
253 key_user # $self->key_user, # the username fieldname
254 key_pass # $self->key_pass, # the password fieldname
255 key_time # $self->key_time, # the server time field name
256 key_save # $self->key_save, # the save password checkbox field name
257 key_redirect # $self->key_redirect, # the redirect fieldname
258 form_name # $self->form_name, # the name of the form
259 script_name # $self->script_name, # where the server will post back to
260 path_info # $self->path_info, # $ENV{PATH_INFO} if any
261 md5_js_path # $self->js_uri_path ."/CGI/Ex/md5.js", # script for cramming
262 $self->key_user # $data->{'user'}, # the username (if any)
263 $self->key_pass # '', # intentional blankout
264 $self->key_time # $self->server_time, # the server's time
265 $self->key_expires_min # $self->expires_min # how many minutes crams are valid
266 text_user # $self->text_user # template text Username:
267 text_pass # $self->text_pass # template text Password:
268 text_save # $self->text_save # template text Save Password ?
269 text_submit # $self->text_submit # template text Login
270 hide_save # $self->hide_save # 0
271 "bounce_on_logout"
273 Default 0. If true, will location bounce to script returned by
274 logout_redirect passing the key key_logout. If false, will simply
275 show the login screen.
276 "key_loggedout"
278 Key to bounce with in the form during a logout should
279 bounce_on_logout return true. Default is "loggedout".
280 "key_logout"
282 If the form hash contains a true value in this field name, the cur‐
283 rent user will be logged out. Default is "cea_logout".
284 "key_cookie"
286 The name of the auth cookie. Default is "cea_user".
287 "key_verify"
289 A field name used during a bounce to see if cookies exist. Default
290 is "cea_verify".
291 "key_user"
293 The form field name used to pass the username. Default is
294 "cea_user".
295 "key_pass"
297 The form field name used to pass the password. Default is
298 "cea_pass".
299 "key_save"
301 Works in conjunction with key_expires_min. If key_save is true,
302 then the cookie will be set to be saved for longer than the current
303 session (If it is a plaintext variety it will be given a 20 year
304 life rather than being a session cookie. If it is a cram variety,
305 the expires_min portion of the cram will be set to -1). If it is
306 set to false, the cookie will be available only for the session (If
307 it is a plaintext variety, the cookie will be session based and
308 will be removed on the next loggout. If it is a cram variety then
309 the cookie will only be good for expires_min minutes.
310 Default is "cea_save".
312 "key_expires_min"
314 The name of the form field that contains how long cram type cookies
315 will be valid if key_save contains a false value.
316 Default key name is "cea_expires_min". Default field value is 6 *
318 60 (six hours).
319 This value will have no effect when use_plaintext or use_crypt is
321 set.
322 A value of -1 means no expiration.
324 "failed_sleep"
326 Number of seconds to sleep if the passed tokens are invalid. Does
327 not apply if validation failed because of expired tokens. Default
328 value is 0. Setting to 0 disables any sleeping.
329 "form_name"
331 The name of the html login form to attach the javascript to.
332 Default is "cea_form".
333 "verify_token"
335 This method verifies the token that was passed either via the form
336 or via cookies. It will accept plaintext or crammed tokens (A
337 listing of the available algorithms for creating tokes is listed
338 below). It also allows for armoring the token with base64 encod‐
339 ing, or using blowfish encryption. A listing of creating these
340 tokens can be found under generate_token.
341 "parse_token"
343 Used by verify_token to remove armor from the passed tokens and
344 split the token into its parts. Returns true if it was able to
345 parse the passed token.
346 "cleanup_user"
348 Called by verify_token. Default is to do no modification. Allows
349 for usernames to be lowercased, or canonized in some other way.
350 Should return the cleaned username.
351 "verify_user"
353 Called by verify_token. Single argument is the username. May or
354 may not be an initial check to see if the username is ok. The
355 username will already be cleaned at this point. Default return is
356 true.
357 "get_pass_by_user"
359 Called by verify_token. Given the cleaned, verified username,
360 should return a valid password for the user. It can always return
361 plaintext. If use_crypt is enabled, it should return the crypted
362 password. If use_plaintext and use_crypt are not enabled, it may
363 return the md5 sum of the password.
364 get_pass_by_user => sub {
366 my ($auth_obj, $user) = @_;
367 my $pass = $some_obj->get_pass({user => $user});
368 return $pass;
369 }
370 Alternately, get_pass_by_user may return a hashref of data items
372 that will be added to the data object if the token is valid. The
373 hashref must also contain a key named real_pass or password that
374 contains the password. Note that keys passed back in the hashref
375 that are already in the data object will override those in the data
376 object.
377 get_pass_by_user => sub {
379 my ($auth_obj, $user) = @_;
380 my ($pass, $user_id) = $some_obj->get_pass({user => $user});
381 return {
382 password => $pass,
383 user_id => $user_id,
384 };
385 }
386 "verify_password"
388 Called by verify_token. Passed the password to check as well as
389 the auth data object. Should return true if the password matches.
390 Default method can handle md5, crypt, cram, secure_hash_cram, and
391 plaintext (all of the default types supported by generate_token).
392 If a property named verify_password exists, it will be used and
393 called as a coderef rather than using the default method.
394 "verify_payload"
396 Called by verify_token. Passed the password to check as well as
397 the auth data object. Should return true if the payload is valid.
398 Default method returns true without performing any checks on the
399 payload. If a property named verify_password exists, it will be
400 used and called as a coderef rather than using the default method.
401 "cgix"
403 Returns a CGI::Ex object.
404 "form"
406 A hash of passed form info. Defaults to CGI::Ex::get_form.
407 "cookies"
409 The current cookies. Defaults to CGI::Ex::get_cookies.
410 "login_template"
412 Should return either a template filename to use for the login tem‐
413 plate, or it should return a reference to a string that contains
414 the template. The contents will be used in login_print and passed
415 to the template engine.
416 Default login_template is the values of login_header, login_form,
418 login_script, and login_script concatenated together.
419 Values from login_hash_common will be passed to the template
421 engine, and will also be used to fill in the form.
422 The basic values are capable of handling most needs so long as
424 appropriate headers and css styles are used.
425 "login_header"
427 Should return a header to use in the default login_template. The
428 default value will try to PROCESS a file called login_header.tt
429 that should be located in directory specified by the tem‐
430 plate_include_path method.
431 It should ideally supply css styles that format the login_form as
433 desired.
434 "login_footer"
436 Same as login_header - but for the footer. Will look for
437 login_footer.tt by default.
438 "login_form"
440 An html chunk that contains the necessary form fields to login the
441 user. The basic chunk has a username text entry, password text
442 entry, save password checkbox, and submit button, and any hidden
443 fields necessary for logging in the user.
444 "login_script"
446 Contains javascript that will attach to the form from login_form.
447 This script is capable of taking the login_fields and creating an
448 md5 cram which prevents the password from being passed plaintext.
449 "text_user, text_pass, text_save"
451 The text items shown in the default login template. The default
452 values are:
453 text_user "Username:"
455 text_pass "Password:"
456 text_save "Save Password ?"
457 "disable_simple_cram"
459 Disables simple cram type from being an available type. Default is
460 false. If set, then one of use_plaintext, use_crypt, or
461 secure_hash_keys should be set. Setting this option allows for
462 payloads to be generated by the server only - otherwise a user who
463 understands the algorithm could generate a valid simple_cram cookie
464 with a custom payload.
465 Another option would be to only accept payloads from tokens if
467 use_blowfish is set and armor was equal to "blowfish."
468
470 This module may be distributed under the same terms as Perl itself.
471
473 Paul Seamons <perl at seamons dot com>
474perl v5.8.8 2007-10-18 CGI::Ex::Auth(3)