1CGI::Application::PlugiUns:e:rAuCtohnetnrtiibcuatCteGidIo:nP:(eA3rp)lplDioccautmieonnt:a:tPiloungin::Authentication(3)
2
3
4

NAME

6       CGI::Application::Plugin::Authentication - Authentication framework for
7       CGI::Application
8

SYNOPSIS

10        package MyCGIApp;
11
12        use base qw(CGI::Application); # make sure this occurs before you load the plugin
13
14        use CGI::Application::Plugin::Authentication;
15
16        MyCGIApp->authen->config(
17              DRIVER => [ 'Generic', { user1 => '123' } ],
18        );
19        MyCGIApp->authen->protected_runmodes('myrunmode');
20
21        sub myrunmode {
22           my $self = shift;
23
24           # The user should be logged in if we got here
25           my $username = $self->authen->username;
26
27        }
28

DESCRIPTION

30       CGI::Application::Plugin::Authentication adds the ability to
31       authenticate users in your CGI::Application modules.  It imports one
32       method called 'authen' into your CGI::Application module.  Through the
33       authen method you can call all the methods of the
34       CGI::Application::Plugin::Authentication plugin.
35
36       There are two main decisions that you need to make when using this
37       module.  How will the usernames and password be verified (i.e. from a
38       database, LDAP, etc...), and how can we keep the knowledge that a user
39       has already logged in persistent, so that they will not have to enter
40       their credentials again on the next request (i.e. how do we 'Store' the
41       authentication information across requests).
42
43   Choosing a Driver
44       There are three drivers that are included with the distribution.  Also,
45       there is built in support for all of the Authen::Simple modules (search
46       CPAN for Authen::Simple for more information).  This should be enough
47       to cover everyone's needs.
48
49       If you need to authenticate against a source that is not provided, you
50       can use the Generic driver which will accept either a hash of
51       username/password pairs, or an array of arrays of credentials, or a
52       subroutine reference that can verify the credentials.  So through the
53       Generic driver you should be able to write your own verification
54       system.  There is also a Dummy driver, which blindly accepts any
55       credentials (useful for testing).  See the
56       CGI::Application::Plugin::Authentication::Driver::Generic,
57       CGI::Application::Plugin::Authentication::Driver::DBI and,
58       CGI::Application::Plugin::Authentication::Driver::Dummy docs for more
59       information on how to use these drivers.  And see the Authen::Simple
60       suite of modules for information on those drivers.
61
62   Choosing a Store
63       The Store modules keep information about the authentication status of
64       the user persistent across multiple requests.  The information that is
65       stored in the store include the username, and the expiry time of the
66       login.  There are two Store modules included with this distribution.  A
67       Session based store, and a Cookie based store.  If your application is
68       already using Sessions (through the CGI::Application::Plugin::Session
69       module), then I would recommend that you use the Session store for
70       authentication.  If you are not using the Session plugin, then you can
71       use the Cookie store.  The Cookie store keeps all the authentication in
72       a cookie, which contains a checksum to ensure that users can not change
73       the information.
74
75       If you do not specify which Store module you wish to use, the plugin
76       will try to determine the best one for you.
77
78   Login page
79       The Authentication plugin comes with a default login page that can be
80       used if you do not want to create a custom login page.  This login form
81       will automatically be used if you do not provide either a LOGIN_URL or
82       LOGIN_RUNMODE parameter in the configuration.  If you plan to create
83       your own login page, I would recommend that you start with the HTML
84       code for the default login page, so that your login page will contain
85       the correct form fields and hidden fields.
86
87   Ticket based authentication
88       This Authentication plugin can handle ticket based authentication
89       systems as well.  All that is required of you is to write a Store
90       module that can understand the contents of the ticket.  The
91       Authentication plugin will require at least the 'username' to be
92       retrieved from the ticket.  A Ticket based authentication scheme will
93       not need a Driver module at all, since the actual verification of
94       credentials is done by an external authentication system, possibly even
95       on a different host.  You will need to specify the location of the
96       login page using the LOGIN_URL configuration variable, and
97       unauthenticated users will automatically be redirected to your ticket
98       authentication login page.
99

EXPORTED METHODS

101   authen
102       This is the only method exported from this module.  Everything is
103       controlled through this method call, which will return a
104       CGI::Application::Plugin::Authentication object, or just the class name
105       if called as a class method.  When using the plugin, you will always
106       first call $self->authen or __PACKAGE__->authen and then the method you
107       wish to invoke.  For example:
108
109         __PACKAGE__->authen->config(
110               LOGIN_RUNMODE => 'login',
111         );
112
113       - or -
114
115         $self->authen->protected_runmodes(qw(one two));
116

METHODS

118   config
119       This method is used to configure the
120       CGI::Application::Plugin::Authentication module.  It can be called as
121       an object method, or as a class method. Calling this function, will not
122       itself generate cookies or session ids.
123
124       The following parameters are accepted:
125
126       DRIVER
127           Here you can choose which authentication module(s) you want to use
128           to perform the authentication.  For simplicity, you can leave off
129           the CGI::Application::Plugin::Authentication::Driver:: part when
130           specifying the DRIVER name  If this module requires extra
131           parameters, you can pass an array reference that contains as the
132           first parameter the name of the module, and the rest of the values
133           in the array will be considered options for the driver.  You can
134           provide multiple drivers which will be used, in order, to check the
135           credentials until a valid response is received.
136
137                DRIVER => 'Dummy' # let anyone in regardless of the password
138
139             - or -
140
141                DRIVER => [ 'DBI',
142                    DBH         => $self->dbh,
143                    TABLE       => 'user',
144                    CONSTRAINTS => {
145                        'user.name'         => '__CREDENTIAL_1__',
146                        'MD5:user.password' => '__CREDENTIAL_2__'
147                    },
148                ],
149
150             - or -
151
152                DRIVER => [
153                    [ 'Generic', { user1 => '123' } ],
154                    [ 'Generic', sub { my ($u, $p) = @_; is_prime($p) ? 1 : 0 } ]
155                ],
156
157             - or -
158
159                DRIVER => [ 'Authen::Simple::LDAP',
160                    host   => 'ldap.company.com',
161                    basedn => 'ou=People,dc=company,dc=net'
162                ],
163
164       STORE
165           Here you can choose how we store the authenticated information
166           after a user has successfully logged in.  We need to store the
167           username so that on the next request we can tell the user has
168           already logged in, and we do not have to present them with another
169           login form.  If you do not provide the STORE option, then the
170           plugin will look to see if you are using the
171           CGI::Application::Plugin::Session module and based on that info use
172           either the Session module, or fall back on the Cookie module.  If
173           the module requires extra parameters, you can pass an array
174           reference that contains as the first parameter the name of the
175           module, and the rest of the array should contain key value pairs of
176           options for this module.  These storage modules generally live
177           under the CGI::Application::Plugin::Authentication::Store:: name-
178           space, and this part of the package name can be left off when
179           specifying the STORE parameter.
180
181               STORE => 'Session'
182
183             - or -
184
185               STORE => ['Cookie',
186                   NAME   => 'MYAuthCookie',
187                   SECRET => 'FortyTwo',
188                   EXPIRY => '1d',
189               ]
190
191       POST_LOGIN_RUNMODE
192           Here you can specify a runmode that the user will be redirected to
193           if they successfully login.
194
195             POST_LOGIN_RUNMODE => 'welcome'
196
197       POST_LOGIN_URL
198           Here you can specify a URL that the user will be redirected to if
199           they successfully login.  If both POST_LOGIN_URL and
200           POST_LOGIN_RUNMODE are specified, then the latter will take
201           precedence.
202
203             POST_LOGIN_URL => 'http://example.com/start.cgi'
204
205       POST_LOGIN_CALLBACK
206           A code reference that is executed after login processing but before
207           POST_LOGIN_RUNMODE or redirecting to POST_LOGIN_URL. This is
208           normally a method in your CGI::Application application and as such
209           the CGI::Application object is passed as a parameter.
210
211             POST_LOGIN_CALLBACK => \&update_login_date
212
213           and later in your code:
214
215             sub update_login_date {
216               my $self = shift;
217
218               return unless($self->authen->is_authenticated);
219
220               ...
221             }
222
223       LOGIN_RUNMODE
224           Here you can specify a runmode that the user will be redirected to
225           if they need to login.
226
227             LOGIN_RUNMODE => 'login'
228
229       LOGIN_URL
230           If your login page is external to this module, then you can use
231           this option to specify a URL that the user will be redirected to
232           when they need to login. If both LOGIN_URL and LOGIN_RUNMODE are
233           specified, then the latter will take precedence.
234
235             LOGIN_URL => 'http://example.com/login.cgi'
236
237       LOGOUT_RUNMODE
238           Here you can specify a runmode that the user will be redirected to
239           if they ask to logout.
240
241             LOGOUT_RUNMODE => 'logout'
242
243       LOGOUT_URL
244           If your logout page is external to this module, then you can use
245           this option to specify a URL that the user will be redirected to
246           when they ask to logout.  If both LOGOUT_URL and LOGOUT_RUNMODE are
247           specified, then the latter will take precedence.
248
249             LOGIN_URL => 'http://example.com/logout.html'
250
251       DETAINT_URL_REGEXP
252           This is a regular expression used to detaint URLs used in the login
253           form. By default it will be set to
254
255             ^([\w\_\%\?\&\;\-\/\@\.\+\$\=\#\:\!\*\"\'\(\)\,]+)$
256
257           This regular expression is based upon the document
258           http://www.w3.org/Addressing/URL/url-spec.txt. You could set it to
259           a more specific regular expression to limit the domains to which
260           users could be directed.
261
262       DETAINT_USERNAME_REGEXP
263           This is a regular expression used to detaint the username parameter
264           used in the login form. By default it will be set to
265
266             ^([\w\_]+)$
267
268       CREDENTIALS
269           Set this to the list of form fields where the user will type in
270           their username and password.  By default this is set to
271           ['authen_username', 'authen_password'].  The form field names
272           should be set to a value that you are not likely to use in any
273           other forms.  This is important because this plugin will
274           automatically look for query parameters that match these values on
275           every request to see if a user is trying to log in.  So if you use
276           the same parameter names on a user management page, you may
277           inadvertently perform a login when that was not intended.  Most of
278           the Driver modules will return the first CREDENTIAL as the
279           username, so make sure that you list the username field first.
280           This option can be ignored if you use the built in login box
281
282             CREDENTIALS => 'authen_password'
283
284             - or -
285
286             CREDENTIALS => [ 'authen_username', 'authen_domain', 'authen_password' ]
287
288       LOGIN_SESSION_TIMEOUT
289           This option can be used to tell the system when to force the user
290           to re-authenticate.  There are a few different possibilities that
291           can all be used concurrently:
292
293           IDLE_FOR
294               If this value is set, a re-authentication will be forced if the
295               user was idle for more then x amount of time.
296
297           EVERY
298               If this value is set, a re-authentication will be forced every
299               x amount of time.
300
301           CUSTOM
302               This value can be set to a subroutine reference that returns
303               true if the session should be timed out, and false if it is
304               still active.  This can allow you to be very selective about
305               how the timeout system works.  The authen object will be passed
306               in as the only parameter.
307
308           Time values are specified in seconds. You can also specify the time
309           by using a number with the following suffixes (m h d w), which
310           represent minutes, hours, days and weeks.  The default is 0 which
311           means the login will never timeout.
312
313           Note that the login is also dependent on the type of STORE that is
314           used.  If the Session store is used, and the session expires, then
315           the login will also automatically expire.  The same goes for the
316           Cookie store.
317
318           For backwards compatibility, if you set LOGIN_SESSION_TIMEOUT to a
319           time value instead of a hashref, it will be treated as an IDLE_FOR
320           time out.
321
322             # force re-authentication if idle for more than 15 minutes
323             LOGIN_SESSION_TIMEOUT => '15m'
324
325             # Everyone must re-authentication if idle for more than 30 minutes
326             # also, everyone must re-authentication at least once a day
327             # and root must re-authentication if idle for more than 5 minutes
328             LOGIN_SESSION_TIMEOUT => {
329                   IDLE_FOR => '30m',
330                   EVERY    => '1d',
331                   CUSTOM   => sub {
332                     my $authen = shift;
333                     return ($authen->username eq 'root' && (time() - $authen->last_access) > 300) ? 1 : 0;
334                   }
335             }
336
337       RENDER_LOGIN
338           This value can be set to a subroutine reference that returns the
339           HTML of a login form. The subroutine reference overrides the
340           default call to login_box.  The subroutine is normally a method in
341           your CGI::Application application and as such the CGI::Application
342           object is passed as the first parameter.
343
344             RENDER_LOGIN => \&login_form
345
346           and later in your code:
347
348             sub login_form {
349               my $self = shift;
350
351               ...
352               return $html
353             }
354
355       LOGIN_FORM
356           You can set this option to customize the login form that is created
357           when a user needs to be authenticated.  If you wish to replace the
358           entire login form with a completely custom version, then just set
359           LOGIN_RUNMODE to point to your custom runmode.
360
361           All of the parameters listed below are optional, and a reasonable
362           default will be used if left blank:
363
364           DISPLAY_CLASS (default: Classic)
365               the class used to display the login form. The alternative is
366               "Basic" which aims for XHTML compliance and leaving style to
367               CSS. See CGI::Application::Plugin::Authentication::Display for
368               more details.
369
370           TITLE (default: Sign In)
371               the heading at the top of the login box
372
373           USERNAME_LABEL (default: User Name)
374               the label for the user name input
375
376           PASSWORD_LABEL (default: Password)
377               the label for the password input
378
379           SUBMIT_LABEL (default: Sign In)
380               the label for the submit button
381
382           COMMENT (default: Please enter your username and password in the
383           fields below.)
384               a message provided on the first login attempt
385
386           REMEMBERUSER_OPTION (default: 1)
387               provide a checkbox to offer to remember the users name in a
388               cookie so that their user name will be pre-filled the next time
389               they log in
390
391           REMEMBERUSER_LABEL (default: Remember User Name)
392               the label for the remember user name checkbox
393
394           REMEMBERUSER_COOKIENAME (default: CAPAUTHTOKEN)
395               the name of the cookie where the user name will be saved
396
397           REGISTER_URL (default: <none>)
398               the URL for the register new account link
399
400           REGISTER_LABEL (default: Register Now!)
401               the label for the register new account link
402
403           FORGOTPASSWORD_URL (default: <none>)
404               the URL for the forgot password link
405
406           FORGOTPASSWORD_LABEL (default: Forgot Password?)
407               the label for the forgot password link
408
409           INVALIDPASSWORD_MESSAGE (default: Invalid username or password<br
410           />(login attempt %d)
411               a message given when a login failed
412
413           INCLUDE_STYLESHEET (default: 1)
414               use this to disable the built in style-sheet for the login box
415               so you can provide your own custom styles
416
417           FORM_SUBMIT_METHOD (default: post)
418               use this to get the form to submit using 'get' instead of
419               'post'
420
421           FOCUS_FORM_ONLOAD (default: 1)
422               use this to automatically focus the login form when the page
423               loads so a user can start typing right away.
424
425           BASE_COLOUR (default: #445588)
426               This is the base colour that will be used in the included login
427               box.  All other colours are automatically calculated based on
428               this colour (unless you hardcode the colour values).  In order
429               to calculate other colours, you will need the Color::Calc
430               module.  If you do not have the Color::Calc module, then you
431               will need to use fixed values for all of the colour options.
432               All colour values besides the BASE_COLOUR can be simple
433               percentage values (including the % sign).  For example if you
434               set the LIGHTER_COLOUR option to 80%, then the calculated
435               colour will be 80% lighter than the BASE_COLOUR.
436
437           LIGHT_COLOUR (default: 50% or #a2aac4)
438               A colour that is lighter than the base colour.
439
440           LIGHTER_COLOUR (default: 75% or #d0d5e1)
441               A colour that is another step lighter than the light colour.
442
443           DARK_COLOUR (default: 30% or #303c5f)
444               A colour that is darker than the base colour.
445
446           DARKER_COLOUR (default: 60% or #1b2236)
447               A colour that is another step darker than the dark colour.
448
449           GREY_COLOUR (default: #565656)
450               A grey colour that is calculated by desaturating the base
451               colour.
452
453   protected_runmodes
454       This method takes a list of runmodes that are to be protected by
455       authentication.  If a user tries to access one of these runmodes, then
456       they will be redirected to a login page unless they are properly logged
457       in.  The runmode names can be a list of simple strings, regular
458       expressions, or special directives that start with a colon.  This
459       method is cumulative, so if it is called multiple times, the new values
460       are added to existing entries.  It returns a list of all entries that
461       have been saved so far.  Calling this function, will not itself
462       generate cookies or session ids.
463
464       :all - All runmodes in this module will require authentication
465
466         # match all runmodes
467         __PACKAGE__->authen->protected_runmodes(':all');
468
469         # only protect runmodes one two and three
470         __PACKAGE__->authen->protected_runmodes(qw(one two three));
471
472         # protect only runmodes that start with auth_
473         __PACKAGE__->authen->protected_runmodes(qr/^auth_/);
474
475         # protect all runmodes that *do not* start with public_
476         __PACKAGE__->authen->protected_runmodes(qr/^(?!public_)/);
477
478   is_protected_runmode
479       This method accepts the name of a runmode, and will tell you if that
480       runmode is a protected runmode (i.e. does a user need to be
481       authenticated to access this runmode).  Calling this function, will not
482       itself generate cookies or session ids.
483
484   redirect_after_login
485       This method is be called during the prerun stage to redirect the user
486       to the page that has been configured as the destination after a
487       successful login.  The location is determined as follows:
488
489       POST_LOGIN_RUNMODE
490           If the POST_LOGIN_RUNMODE config parameter is set, that run mode
491           will be the chosen location.
492
493       POST_LOGIN_URL
494           If the above fails and the POST_LOGIN_URL config parameter is set,
495           then there will be a 302 redirection to that location.
496
497       destination
498           If the above fails and there is a destination query parameter,
499           which must a taint check against the DETAINT_URL_REGEXP config
500           parameter, then there will be a 302 redirection to that location.
501
502       original destination
503           If all the above fail then there the originally requested page will
504           be delivered.
505
506   redirect_to_login
507       This method is be called during the prerun stage if the current user is
508       not logged in, and they are trying to access a protected runmode.  It
509       will redirect to the page that has been configured as the login page,
510       based on the value of LOGIN_RUNMODE or LOGIN_URL  If nothing is
511       configured a simple login page will be automatically provided.
512
513   redirect_to_logout
514       This method is called during the prerun stage if the user has requested
515       to be logged out.  It will redirect to the page that has been
516       configured as the logout page, based on the value of LOGOUT_RUNMODE or
517       LOGOUT_URL  If nothing is configured, the page will redirect to the
518       website homepage.
519
520   setup_runmodes
521       This method is called during the prerun stage to register some custom
522       runmodes that the Authentication plugin requires in order to function.
523       Calling this function, will not itself generate cookies or session ids.
524
525   last_login
526       This will return return the time of the last login for this user
527
528         my $last_login = $self->authen->last_login;
529
530       This function will initiate a session or cookie if one has not been
531       created already.
532
533   last_access
534       This will return return the time of the last access for this user
535
536         my $last_access = $self->authen->last_access;
537
538       This function will initiate a session or cookie if one has not been
539       created already.
540
541   is_login_timeout
542       This will return true or false depending on whether the users login
543       status just timed out
544
545         $self->add_message('login session timed out') if $self->authen->is_login_timeout;
546
547       This function will initiate a session or cookie if one has not been
548       created already.
549
550   is_authenticated
551       This will return true or false depending on the login status of this
552       user
553
554         assert($self->authen->is_authenticated); # The user should be logged in if we got here
555
556       This function will initiate a session or cookie if one has not been
557       created already.
558
559   login_attempts
560       This method will return the number of failed login attempts have been
561       made by this user since the last successful login.  This is not a
562       number that can be trusted, as it is dependent on the underlying store
563       to be able to return the correct value for this user.  For example, if
564       the store uses a cookie based session, the user trying to login could
565       delete their cookies, and hence get a new session which will not have
566       any login attempts listed.  The number will be cleared upon a
567       successful login.  This function will initiate a session or cookie if
568       one has not been created already.
569
570   username
571       This will return the username of the currently logged in user, or undef
572       if no user is currently logged in.
573
574         my $username = $self->authen->username;
575
576       This function will initiate a session or cookie if one has not been
577       created already.
578
579   is_new_login
580       This will return true or false depending on if this is a fresh login
581
582         $self->log->info("New Login") if $self->authen->is_new_login;
583
584       This function will initiate a session or cookie if one has not been
585       created already.
586
587   credentials
588       This method will return the names of the form parameters that will be
589       looked for during a login.  By default they are authen_username and
590       authen_password, but these values can be changed by supplying the
591       CREDENTIALS parameters in the configuration. Calling this function,
592       will not itself generate cookies or session ids.
593
594   logout
595       This will attempt to logout the user.  If during a request the
596       Authentication module sees a parameter called 'authen_logout', it will
597       automatically call this method to log out the user.
598
599         $self->authen->logout();
600
601       This function will initiate a session or cookie if one has not been
602       created already.
603
604   drivers
605       This method will return a list of driver objects that are used for
606       verifying the login credentials. Calling this function, will not itself
607       generate cookies or session ids.
608
609   store
610       This method will return a store object that is used to store
611       information about the status of the authentication across multiple
612       requests.  This function will initiate a session or cookie if one has
613       not been created already.
614
615   initialize
616       This does most of the heavy lifting for the Authentication plugin.  It
617       will check to see if the user is currently attempting to login by
618       looking for the credential form fields in the query object.  It will
619       load the required driver objects and authenticate the user.  It is OK
620       to call this method multiple times as it checks to see if it has
621       already been executed and will just return without doing anything if
622       called multiple times.  This allows us to call initialize as late as
623       possible in the request so that no unnecessary work is done.
624
625       The user will be logged out by calling the logout() method if the login
626       session has been idle for too long, if it has been too long since the
627       last login, or if the login has timed out.  If you need to know if a
628       user was logged out because of a time out, you can call the
629       "is_login_timeout" method.
630
631       If all goes well, a true value will be returned, although it is usually
632       not necessary to check.
633
634       This function will initiate a session or cookie if one has not been
635       created already.
636
637   display
638       This method will return the
639       CGI::Application::Plugin::Authentication::Display object, creating and
640       caching it if necessary.
641
642   login_box
643       This method will return the HTML for a login box that can be embedded
644       into another page.  This is the same login box that is used in the
645       default authen_login runmode that the plugin provides.
646
647       This function will initiate a session or cookie if one has not been
648       created already.
649
650   new
651       This method creates a new CGI::Application::Plugin::Authentication
652       object.  It requires as it's only parameter a CGI::Application object.
653       This method should never be called directly, since the 'authen' method
654       that is imported into the CGI::Application module will take care of
655       creating the CGI::Application::Plugin::Authentication object when it is
656       required. Calling this function, will not itself generate cookies or
657       session ids.
658
659   instance
660       This method works the same way as 'new', except that it returns the
661       same Authentication object for the duration of the request.  This
662       method should never be called directly, since the 'authen' method that
663       is imported into the CGI::Application module will take care of creating
664       the CGI::Application::Plugin::Authentication object when it is
665       required. Calling this function, will not itself generate cookies or
666       session ids.
667

CGI::Application CALLBACKS

669   prerun_callback
670       This method is a CGI::Application prerun callback that will be
671       automatically registered for you if you are using CGI::Application 4.0
672       or greater.  If you are using an older version of CGI::Application you
673       will have to create your own cgiapp_prerun method and make sure you
674       call this method from there.
675
676        sub cgiapp_prerun {
677           my $self = shift;
678
679           $self->CGI::Application::Plugin::Authentication::prerun_callback();
680        }
681

CGI::Application RUNMODES

683   authen_login_runmode
684       This runmode is provided if you do not want to create your own login
685       runmode.  It will display a simple login form for the user, which can
686       be replaced by assigning RENDER_LOGIN a coderef that returns the HTML.
687
688   authen_dummy_redirect
689       This runmode is provided for convenience when an external redirect
690       needs to be done.  It just returns an empty string.
691

EXAMPLE

693       In a CGI::Application module:
694
695         use base qw(CGI::Application);
696         use CGI::Application::Plugin::AutoRunmode;
697         use CGI::Application::Plugin::Session;
698         use CGI::Application::Plugin::Authentication;
699
700         __PACKAGE__->authen->config(
701               DRIVER         => [ 'Generic', { user1 => '123' } ],
702               STORE          => 'Session',
703               LOGOUT_RUNMODE => 'start',
704         );
705         __PACKAGE__->authen->protected_runmodes(qr/^auth_/, 'one');
706
707         sub start : RunMode {
708           my $self = shift;
709
710         }
711
712         sub one : RunMode {
713           my $self = shift;
714
715           # The user will only get here if they are logged in
716         }
717
718         sub auth_two : RunMode {
719           my $self = shift;
720
721           # This is also protected because of the
722           # regexp call to protected_runmodes above
723         }
724

COMPATIBILITY WITH CGI::Application::Plugin::ActionDispatch

726       The prerun callback has been modified so that it will check for the
727       presence of a prerun mode.  This is for compatibility with
728       CGI::Application::Plugin::ActionDispatch. This change should be
729       considered experimental. It is necessary to load the ActionDispatch
730       module so that the two prerun callbacks will be called in the correct
731       order.
732
734       CSS The best practice nowadays is generally considered to be to not
735           have CSS embedded in HTML. Thus it should be best to set LOGIN_FORM
736           -> DISPLAY_CLASS to 'Basic'.
737
738       Post login destination
739           Of the various means of selecting a post login destination the most
740           secure would seem to be POST_LOGIN_URL. The "destination" parameter
741           could potentially be hijacked by hackers.  The POST_LOGIN_RUNMODE
742           parameter requires a hidden parameter that could potentially be
743           hijacked.
744
745       Taint mode
746           Do run your code under taint mode. It should help protect your
747           application against a number of attacks.
748
749       URL and username checking
750           Please set the "DETAINT_URL_REGEXP" and "DETAINT_USERNAME_REGEXP"
751           parameters as tightly as possible. In particular you should prevent
752           the destination parameter being used to redirect authenticated
753           users to external sites; unless of course that is what you want in
754           which case that site should be the only possible external site.
755
756       The login form
757           The HTML currently generated does not seem to be standards
758           compliant as per RT bug 58023. Also the default login form includes
759           hidden forms which could conceivably be hijacked.  Set LOGIN_FORM
760           -> DISPLAY_CLASS to 'Basic' to fix this.
761

TODO

763       There are lots of things that can still be done to improve this plugin.
764       If anyone else is interested in helping out feel free to dig right in.
765       Many of these things don't need my input, but if you want to avoid
766       duplicated efforts, send me a note, and I'll let you know of anyone
767       else is working in the same area.
768
769       review the code for security bugs and report
770       complete the separation of presentation and logic
771       write a tutorial
772       build more Drivers (Class::DBI, LDAP, Radius, etc...)
773       Add support for method attributes to identify runmodes that require
774       authentication
775       finish the test suite
776       provide more example code
777       clean up the documentation
778       build a DB driver that builds it's own table structure.  This can be
779       used by people that don't have their own user database to work with,
780       and could include a simple user management application.
781

BUGS

783       This is alpha software and as such, the features and interface are
784       subject to change.  So please check the Changes file when upgrading.
785
786       Some of the test scripts appear to be incompatible with versions of
787       Devel::Cover later than 0.65.
788

SEE ALSO

790       CGI::Application, perl(1)
791

AUTHOR

793       Author: Cees Hek <ceeshek@gmail.com>; Co-maintainer: Nicholas Bamber
794       <nicholas@periapt.co.uk>.
795

CREDITS

797       Thanks to SiteSuite <http://www.sitesuite.com.au> for funding the
798       development of this plugin and for releasing it to the world.
799
800       Thanks to Christian Walde for suggesting changes to fix the
801       incompatibility with CGI::Application::Plugin::ActionDispatch and for
802       help with github.
803
804       Thanks to Alexandr Ciornii for pointing out some typos.
805
807       Copyright (c) 2005, SiteSuite. All rights reserved.  Copyright (c)
808       2010, Nicholas Bamber. (Portions of the code).
809
810       This module is free software; you can redistribute it and/or modify it
811       under the same terms as Perl itself.
812
813       The background images in the default login forms are used courtesy of
814       www.famfamfam.com <http://www.famfamfam.com/lab/icons/silk/>. Those
815       icons are issued under the Creative Commons Attribution 3.0 License
816       <http://creativecommons.org/licenses/by/3.0/>.  Those icons are
817       copyrighted 2006 by Mark James <mjames at gmail dot com>
818

DISCLAIMER OF WARRANTY

820       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
821       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
822       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
823       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
824       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
825       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
826       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
827       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
828       NECESSARY SERVICING, REPAIR, OR CORRECTION.
829
830       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
831       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
832       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
833       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
834       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
835       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
836       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
837       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
838       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
839       DAMAGES.
840
841
842
843perl v5.36.0                      20C2G3I-:0:1A-p2p0lication::Plugin::Authentication(3)
Impressum