caf.pod

   1 =head1 NAME
   2
   3 CGI::Auth::Flexible - web authentication optionally using cookies
   4
   5 =head1 SYNOPSYS
   6
   7  my $verifier = CGI::Auth::Flexible->new_verifier(setting => value,...);
   8  my $authreq = $verifier->new_request($cgi_query_object);
   9
  10  # simple applications
  11  $authreq->check_ok() or return;
  12
  13  # sophisticated applications
  14  my $divert_kind = $authreq->check_divert();
  15  if ($divert_kind) { ... print diversion page and quit ... }
  16
  17  # while handling the request
  18  $user = $authreq->get_username();
  19  $authreq->check_mutate();
  20
  21 =head1 DESCRIPTION
  22
  23 CGI::Auth::Flexible is a library which you can use to add a
  24 forms/cookie-based login facility to a Perl web application.
  25
  26 CGI::Auth::Flexible doesn't interfere with your application's URL path
  27 namespace and just needs a few (configurable) form parameter and
  28 cookie name(s) for its own use.  It tries to avoid making assumptions
  29 about the implementation structure of your application.
  30
  31 Because CGI::Auth::Flexible is licenced under the AGPLv3, you will
  32 probably need to provide a facility to allow users (even ones not
  33 logged in) to download the source code for your web app.  Conveniently
  34 by default CGI::Auth::Flexible provides (for pure Perl webapps) a
  35 mechanism for users to get the source.
  36
  37 CGI::Auth::Flexible is designed to try to stop you accidentally
  38 granting access by misunderstanding the API.  (Also it, of course,
  39 guards against cross-site scripting.)  You do need to make sure to
  40 call CGI::Auth::Flexible before answering AJAX requests as well as
  41 before generating HTML pages, of course, and to call it in every
  42 entrypoint to your system.
  43
  44 =head2 INITIALISATION
  45
  46 Your application should, on startup (eg, when it is loaded by
  47 mod_perl) do
  48 C<< $verifier = CGI::Auth::Flexible->new_verifier(settings...) >>.
  49 This call can be expensive and is best amortised.
  50
  51 The resulting verifier object can be used to process individual
  52 requests, in each case with
  53 C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>.
  54
  55 =head2 SIMPLE APPLICATIONS
  56
  57 The simplist usage is to call C<< $request->check_ok() >> which will
  58 check the user's authentication.  If the user is not logged in it will
  59 generate a login form (or redirection or other appropriate page) and
  60 return false; your application should not then processing that request
  61 any further.  If the user is logged in it will return true.
  62
  63 After calling C<check_ok> you can use C<< $request->get_username >>
  64 to find out which user the request came from.
  65
  66 =head2 SOPHISTICATED APPLICATIONS
  67
  68 If you want to handle the flow control and to generate login forms,
  69 redirections, etc., yourself, you can say
  70 C<< $divert = $request->check_divert >>.  This returns undef if
  71 the user is logged in, or I<divert spec> if some kind of login
  72 page or diversion should be generated.
  73
  74 =head2 GENERATING (MUTATING) FORMS AND AJAX QUERIES
  75
  76 When you generate a C<POST> form or AJAX request you need to include a
  77 special secret hidden form parameter for the benefit of
  78 CGI::Auth::Generic.  This form parameter will be checked by
  79 C<check_ok>/C<check_divert> and should be ignored by your application.
  80
  81 By default the hidden parameter is called C<caf_assochash>.  After
  82 calling C<check_ok> or C<check_divert> the value to put in your form
  83 can be obtained from C<secret_hidden_val>; C<secret_hidden_html> will
  84 generate the whole HTML C<< <input...> >> element.
  85
  86 Do not put the secret value in URLs for C<GET> requests.
  87
  88 =head2 MUTATING OPERATIONS AND EXTERNAL LINKS INTO YOUR SITE
  89
  90 By default CGI::Auth::Flexible does not permit external links into
  91 your site.  All GET requests give a "click to continue" page which
  92 submits a form which loads your app's main page.  In this
  93 configuration all your application's forms and AJAX requests should
  94 use C<POST>.  This restriction arises from complicated deficiencies
  95 in the web's security architecture.
  96
  97 The alternative is for your application to always make a special check
  98 when the incoming request is going to do some kind of action (such as
  99 modifying the user's setup, purchasing goods, or whatever) rather than
 100 just display HTML pages.  Then non-mutating pages can be linked to
 101 from other, untrustworthy, websites.
 102
 103 To support external links, and C<GET> requests, pass
 104 C<< promise_check_mutate => 1 >> in I<settings>, and then call
 105 C<< $authreq->check_mutate() >> before taking any actions.  If the
 106 incoming request is not suitable then C<< $authreq->check_mutate() >>
 107 will call C<die>.
 108
 109 You must make sure that you have no mutating C<GET> requests in your
 110 application - but you shouldn't have any of those anyway.
 111
 112 =head2 DATA STORAGE
 113
 114 CGI::Auth::Flexible needs to store various information in plain files;
 115 it does this in the directory specified by the C<dir> parameter.
 116
 117 =head1 SOURCE CODE DOWNLOAD
 118
 119 By default, CGI::Auth::Flexible provides a facility for users to
 120 download the source code for the running version of your web
 121 application.
 122
 123 This facility makes a number of important assumptions which you need
 124 to check.  Note that if the provided facility is not sufficient
 125 because your application is more sophisticated than it copes with (or
 126 if you disable the builtin facility), you may need to implement a
 127 functioning alternative to avoid violating the AGPLv3 licence.
 128
 129 Here are the most important (default) assumptions:
 130
 131 =over
 132
 133 =item *
 134
 135 Your app's source code is available by looking at @INC, $0 and
 136 S<$ENV{'SCRIPT_FILENAME'}> (the B<source items>).  See
 137 C<srcdump_listitems>.  Where these point to files or directories under
 138 revision control, the source item is the whole containing vcs tree.
 139
 140 =item *
 141
 142 Specifically, there are no compiled or autogenerated Perl
 143 files, Javascript resources, etc., which are not contained in one of
 144 the source item directories.  (Files which came with your operating
 145 system install don't need to be shipped as they fall under the system
 146 library exceptio.)
 147
 148 =item *
 149
 150 You have not installed any modified versions of system
 151 libraries (including system-supplied) Perl modules in C</usr> outside
 152 C</usr/local>.  See C<srcdump_system_dir>.
 153
 154 =item *
 155
 156 For each source item in a dvcs, the entire dvcs history does
 157 not contain anything confidential (or libellous).  Also, all files which
 158 contain secrets are in the dvcs's C<.ignore> file.  See
 159 C<srcdump_vcsscript_git> et al.
 160
 161 =item *
 162
 163 For each source item NOT in a dvcs, there are no confidential
 164 files with the world-readable bit set (being in a world-inaccessible
 165 directory is not sufficient).  See C<srcdump_excludes>.
 166
 167 =item *
 168
 169 You have none of your app's source code in C</etc>.
 170
 171 =item *
 172
 173 You don't regard pathnames on your server as secret.
 174
 175 =item *
 176
 177 You don't intentionally load Perl code by virtule of C<.>
 178 being in C<@INC> by default.  (See C<srcdump_filter_cwd>.)
 179
 180 =back
 181
 182 =head1 MAIN FUNCTIONS AND METHODS
 183
 184 =over
 185
 186 =item C<< CGI::Auth::Flexible->new_verifier(setting => value, ...) >>
 187
 188 Initialises an instance and returns a verifier object.
 189 The arguments are setting pairs like a hash initialiser.
 190 See L</SETTINGS> below.
 191
 192 =item C<< $verifier->new_request($cgi_query) >>
 193
 194 Prepares to process a request.  C<$cgi_query> should normally
 195 be the query object from L<CGI(3perl)>.  Most of the default
 196 hook methods assume that it is; however if you replace enough of
 197 the hook methods then you can pass any value you like and it
 198 will be passed to your hooks.
 199
 200 The return value is the authentication request object (C<$authreq>)
 201 which is used to check the incoming request and will contain
 202 information about its credentials.
 203
 204 =item C<< $authreq->check_divert() >>
 205
 206 Checks whether the user is logged in.  Returns undef if the user is
 207 logged in and we should service the request.  Otherwise returns a
 208 divert spec (see L</DIVERT SPEC>) saying what should happen instead.
 209
 210 This method may die if it doesn't like the request, in which case
 211 the request needs to be rejected.
 212
 213 =item C<< $authreq->check_ok() >>
 214
 215 Checks whether the user is logged in.  Returns true if the user is
 216 logged in and we should service the request.
 217
 218 Otherwise it handles the request itself, generating any appropriate
 219 redirect, login form, or continuation page.  It then returns false and
 220 the application should not process the request further.
 221
 222 =item C<< $verifier->disconnect() >>
 223
 224 Discards the resources (open files, etc.) in the verifier object.
 225
 226 =back