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 NON-PAGE RESOURCES
  89
  90 Some, but not all, non-page resources (fetched with GET) need to have
  91 the secret hidden parameter in the query parameters in the form url.
  92
  93 So if your application supports anything except HTML pages you need to
  94 take special measures.  (Wholly invariant resources which don't depend
  95 on which user is logged in are an exception.)
  96
  97 When you generate a url to such a resource you must call
  98 resource_get_needs_secret_hidden to find out whether to include the
  99 hidden form parameter  xxx fixme
 100
 101 You can only when logged in
 102
 103  call
 104 C<nonpage_ok> when you are processing one of these.  You need to
 105 supply a parameter specifying exactly what kind of resource this is:
 106
 107
 108
 109 before you
 110 generate any output
 111
 112  (other than
 113
 114
 115 =head2 MUTATING OPERATIONS AND EXTERNAL LINKS INTO YOUR SITE
 116
 117 By default CGI::Auth::Flexible does not permit external links into
 118 your site.  All GET requests give a "click to continue" page which
 119 submits a form which loads your app's main page.  In this
 120 configuration all your application's forms and AJAX requests should
 121 use C<POST>.  This restriction arises from complicated deficiencies
 122 in the web's security architecture.
 123
 124 The alternative is for your application to always make a special check
 125 when the incoming request is going to do some kind of action (such as
 126 modifying the user's setup, purchasing goods, or whatever) rather than
 127 just display HTML pages.  Then non-mutating pages can be linked to
 128 from other, untrustworthy, websites.
 129
 130 To support external links, and C<GET> requests, pass
 131 C<< promise_check_mutate => 1 >> in I<settings>, and then call
 132 C<< $authreq->check_mutate() >> before taking any actions.  If the
 133 incoming request is not suitable then C<< $authreq->check_mutate() >>
 134 will call C<die>.
 135
 136 You must make sure that you have no mutating C<GET> requests in your
 137 application - but you shouldn't have any of those anyway.
 138
 139 =head2 DATA STORAGE
 140
 141 CGI::Auth::Flexible needs to store various information in plain files;
 142 it does this in the directory specified by the C<dir> parameter.
 143
 144 =head1 SOURCE CODE DOWNLOAD
 145
 146 By default, CGI::Auth::Flexible provides a facility for users to
 147 download the source code for the running version of your web
 148 application.
 149
 150 This facility makes a number of important assumptions which you need
 151 to check.  Note that if the provided facility is not sufficient
 152 because your application is more sophisticated than it copes with (or
 153 if you disable the builtin facility), you may need to implement a
 154 functioning alternative to avoid violating the AGPLv3 licence.
 155
 156 Here are the most important (default) assumptions:
 157
 158 =over
 159
 160 =item *
 161
 162 Your app's source code is available by looking at @INC, $0 and
 163 S<$ENV{'SCRIPT_FILENAME'}> (the B<source items>).  See
 164 C<srcdump_listitems>.  Where these point to files or directories under
 165 revision control, the source item is the whole containing vcs tree.
 166
 167 =item *
 168
 169 Specifically, there are no compiled or autogenerated Perl
 170 files, Javascript resources, etc., which are not contained in one of
 171 the source item directories.  (Files which came with your operating
 172 system install don't need to be shipped as they fall under the system
 173 library exceptio.)
 174
 175 =item *
 176
 177 You have not installed any modified versions of system
 178 libraries (including system-supplied) Perl modules in C</usr> outside
 179 C</usr/local>.  See C<srcdump_system_dir>.
 180
 181 =item *
 182
 183 For each source item in a dvcs, the entire dvcs history does
 184 not contain anything confidential (or libellous).  Also, all files which
 185 contain secrets are in the dvcs's C<.ignore> file.  See
 186 C<srcdump_vcsscript_git> et al.
 187
 188 =item *
 189
 190 For each source item NOT in a dvcs, there are no confidential
 191 files with the world-readable bit set (being in a world-inaccessible
 192 directory is not sufficient).  See C<srcdump_excludes>.
 193
 194 =item *
 195
 196 You have none of your app's source code in C</etc>.
 197
 198 =item *
 199
 200 You don't regard pathnames on your server as secret.
 201
 202 =item *
 203
 204 You don't intentionally load Perl code by virtule of C<.>
 205 being in C<@INC> by default.  (See C<srcdump_filter_cwd>.)
 206
 207 =back
 208
 209 =head1 MAIN FUNCTIONS AND METHODS
 210
 211 =over
 212
 213 =item C<< CGI::Auth::Flexible->new_verifier(setting => value, ...) >>
 214
 215 Initialises an instance and returns a verifier object.
 216 The arguments are setting pairs like a hash initialiser.
 217 See L</SETTINGS> below.
 218
 219 =item C<< $verifier->new_request($cgi_query) >>
 220
 221 Prepares to process a request.  C<$cgi_query> should normally
 222 be the query object from L<CGI(3perl)>.  Most of the default
 223 hook methods assume that it is; however if you replace enough of
 224 the hook methods then you can pass any value you like and it
 225 will be passed to your hooks.
 226
 227 The return value is the authentication request object (C<$authreq>)
 228 which is used to check the incoming request and will contain
 229 information about its credentials.
 230
 231 =item C<< $authreq->check_divert() >>
 232
 233 Checks whether the user is logged in.  Returns undef if the user is
 234 logged in and we should service the request.  Otherwise returns a
 235 divert spec (see L</DIVERT SPEC>) saying what should happen instead.
 236
 237 This method may die if it doesn't like the request, in which case
 238 the request needs to be rejected.
 239
 240 =item C<< $authreq->check_ok() >>
 241
 242 Checks whether the user is logged in.  Returns true if the user is
 243 logged in and we should service the request.
 244
 245 Otherwise it handles the request itself, generating any appropriate
 246 redirect, login form, or continuation page.  It then returns false and
 247 the application should not process the request further.
 248
 249 =item C<< $verifier->disconnect() >>
 250
 251 Discards the resources (open files, etc.) in the verifier object.
 252
 253 =back