before generating HTML pages, of course, and to call it in every
entrypoint to your system.
-=head1 INITIALISATION
+=head2 INITIALISATION
Your application should, on startup (eg, when it is loaded by
mod_perl) do
requests, in each case with
C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>.
-=head1 SIMPLE APPLICATIONS
+=head2 SIMPLE APPLICATIONS
The simplist usage is to call C<< $request->check_ok() >> which will
check the user's authentication. If the user is not logged in it will
After calling C<check_ok> you can use C<< $request->get_username >>
to find out which user the request came from.
-=head1 SOPHISTICATED APPLICATIONS
+=head2 SOPHISTICATED APPLICATIONS
If you want to handle the flow control and to generate login forms,
redirections, etc., yourself, you can say
the user is logged in, or I<divert spec> if some kind of login
page or diversion should be generated.
-=head1 MUTATING OPERATIONS AND EXTERNAL LINKS INTO YOUR SITE
+=head2 GENERATING (MUTATING) FORMS AND AJAX QUERIES
+
+When you generate a C<POST> form or AJAX request you need to include a
+special secret hidden form parameter for the benefit of
+CGI::Auth::Generic. This form parameter will be checked by
+C<check_ok>/C<check_divert> and should be ignored by your application.
+
+By default its name is C<caf_assochash>. After calling C<check_ok> or
+C<check_divert> the value to put in your form can be obtained from
+C<secret_hidden_val>; C<secret_hidden_html> will generate the whole
+HTML C<< <input...> >> element.
+
+Do not put the secret value in URLs for C<GET> requests.
+
+=head2 MUTATING OPERATIONS AND EXTERNAL LINKS INTO YOUR SITE
By default CGI::Auth::Flexible does not permit external links into
your site. All GET requests give a "click to continue" page which
-submits a form.
+submits a form. In this configuration all your application's forms
+and AJAX requests should use C<POST>.
This is because the alternative (for complicated reasons relating to
the web security architecture) is to require your application to make
some kind of action (such as modifying the user's setup, purchasing
goods, or whatever) rather than just display HTML pages.
-To support external links, pass C<< promise_check_mutate => 1 >> in
-I<settings>, and then call C<< $authreq->check_mutate() >> before
-taking any actions. If the incoming request is not suitable then
-C<< $authreq->check_mutate() >> will call C<die>. If you do this you
-must make sure that you have no mutating C<GET> requests in your
-application - but you shouldn't have any of those anyway.
+To support external links, and C<GET> requests, pass C<<
+promise_check_mutate => 1 >> in I<settings>, and then call C<<
+$authreq->check_mutate() >> before taking any actions. If the
+incoming request is not suitable then C<< $authreq->check_mutate() >>
+will call C<die>. If you do this you must make sure that you have no
+mutating C<GET> requests in your application - but you shouldn't have
+any of those anyway.
+
+=head2 DATA STORAGE
+
+CGI::Auth::Flexible needs to store various information in plain files;
+it does this in the directory specified by the C<dir> parameter.
+
+It also needs to record state relating to user sessions in a database.
+There is no particular reason for this
=head1 SOURCE CODE DOWNLOAD
=back
-=head1 FUNCTIONS AND METHODS
+=head1 MAIN FUNCTIONS AND METHODS
=over
-=item C<< CGI::Auth::Flexible::new_verifier(setting => value, ...) >>
+=item C<< CGI::Auth::Flexible->new_verifier(setting => value, ...) >>
Initialises an instance and returns a verifier object.
The arguments are setting pairs like a hash initialiser.
logged in and we should service the request. Otherwise returns a
divert spec (see L</DIVERT SPEC>) saying what should happen instead.
+This method may die if it doesn't like the request, in which case
+the request needs to be rejected.
+
+=item C<< $authreq->check_ok() >>
+
+Checks whether the user is logged in. Returns true if the user is
+logged in and we should service the request.
+
+Otherwise it handles the request itself, generating any appropriate
+redirect, login form, or continuation page. It then returns false and
+the application should not process the request further.
+
+=item C<< $authreq->disconnect() >>
+
+Disconnects from the
+
=back
~ian / cgi-auth-flexible.git / blobdiff