Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
=head3 Simple applications
=head3 Simple applications
-The simplist usage is to call C<< $request->check_ok() >> which will
+The simplest usage is to call C<< $request->check_ok() >> which will
check the user's authentication. If the user is not logged in it will
generate a login form (or redirection or other appropriate page) and
check the user's authentication. If the user is not logged in it will
generate a login form (or redirection or other appropriate page) and
-return false; your application should not then processing that request
+return false; your application should not then process that request
any further. If the user is logged in it will return true.
Various hooks are provided to customise the responses generated by
any further. If the user is logged in it will return true.
Various hooks are provided to customise the responses generated by
After C<check_ok> returns true you should go ahead and process the
request; you can use C<< $request->get_username >> to find out which
user the request came from.
After C<check_ok> returns true you should go ahead and process the
request; you can use C<< $request->get_username >> to find out which
user the request came from.
+You may also need to call C<check_mutate> and/or C<check_nonpage>
+- see below.
-=head2 Sophisticated applications
+=head3 Sophisticated applications
If you want to handle the control flow and to generate login forms,
redirections, etc., yourself, you can say
C<< $divert = $request->check_divert >>. This returns undef if
If you want to handle the control flow and to generate login forms,
redirections, etc., yourself, you can say
C<< $divert = $request->check_divert >>. This returns undef if
-the user is logged in, or I<divert spec> if some kind of login
+the user is logged in, or
a I<divert spec> if some kind of login
page or diversion should be generated. See L</DIVERT SPEC> below for
details of how to deal with the return value.
page or diversion should be generated. See L</DIVERT SPEC> below for
details of how to deal with the return value.
=head3 Mutation-ignorant applications
=head3 Mutation-ignorant applications
-By default CGI::Auth::Flexible does not permit external links into
-your site. All GET requests give a "click to continue" page which
+By default CGI::Auth::Flexible does not permit external deep links
+into your site.
+All GET requests give a "click to continue" page which
submits a form which loads your app's main page. In this
configuration all your application's forms and AJAX requests should
submits a form which loads your app's main page. In this
configuration all your application's forms and AJAX requests should
-use C<POST>. This restriction arises from complicated deficiencies
-in the web's security architecture.
Such applications are also not able to provide user-specific CSS
stylesheets, javascript, favicons, etc.
Such applications are also not able to provide user-specific CSS
stylesheets, javascript, favicons, etc.
+This restriction arises from complicated deficiencies
+in the web's security architecture.
+
=head3 Mutation-aware applications
The alternative is for your application to always make a special check
=head3 Mutation-aware applications
The alternative is for your application to always make a special check
CGI::Auth::Generic. This form parameter will be checked by
C<check_ok>/C<check_divert> and should be ignored by your application.
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 the hidden parameter is called C<caf_assochash>.
+By default the hidden parameter is called 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>
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>
been called. (In the case of C<check_ok> it won't normally be sensible
to call these functions unless C<check_ok> returned true.)
been called. (In the case of C<check_ok> it won't normally be sensible
to call these functions unless C<check_ok> returned true.)
=item C<< $authreq->get_divert() >>
Returns the value previously returned by C<check_divert>.
=item C<< $authreq->get_divert() >>
Returns the value previously returned by C<check_divert>.
is well and the request should proceed, or it will die, like
C<check_mutate>.
is well and the request should proceed, or it will die, like
C<check_mutate>.
=head1 RESPONSE-RELATED FUNCTIONS AND METHODS
=head1 RESPONSE-RELATED FUNCTIONS AND METHODS
=item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
Convenience function which returns a url for a GET request to this
=item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
Convenience function which returns a url for a GET request to this
cookie in the forms generated by C<check_ok>. You may also set it
yourself (and indeed you must do so if you use C<check_divert>).
cookie in the forms generated by C<check_ok>. You may also set it
yourself (and indeed you must do so if you use C<check_divert>).
-item C<< $authreq->_chain_params() >>
+=item C<< $authreq->_chain_params() >>
Returns a hash of the "relevant" parameters to this request, in a form
suitable for C<url_with_query_params>. This is all of the query
Returns a hash of the "relevant" parameters to this request, in a form
suitable for C<url_with_query_params>. This is all of the query
I<$reqtype> is the request type (the value which will be passed to
C<check_nonpage> and C<need_add_hidden>. If you are supporting a new
I<$reqtype> is the request type (the value which will be passed to
C<check_nonpage> and C<need_add_hidden>. If you are supporting a new
-I<$reqtype> you shouuld coordinate with CGI::Auth::Flexible upstrea,
+I<$reqtype> you shouuld coordinate with CGI::Auth::Flexible upstream,
or other users, to assign a unique request type name.
This method may be called on an authreq or a verifier, in which case
or other users, to assign a unique request type name.
This method may be called on an authreq or a verifier, in which case
C<< XMLHttpRequest >> returning data of some other kind. (Possibly
confidential for the user.)
C<< XMLHttpRequest >> returning data of some other kind. (Possibly
confidential for the user.)
+Provided with diversion kinds which involve
+generating a redirection or indirection,
+perhaps via a login form.
+
The extra hidden form parameters (and the C<PATH_INFO>) which should
be set when the subsequent request bounces back from the client, in
the form used by C<url_with_query_params>.
The extra hidden form parameters (and the C<PATH_INFO>) which should
be set when the subsequent request bounces back from the client, in
the form used by C<url_with_query_params>.
(Applications which set C<promise_check_mutate> do not see this divert
kind.)
(Applications which set C<promise_check_mutate> do not see this divert
kind.)
=head1 SETTINGS
C<new_verifier> and C<new_request> each take a list of settings, as
=head1 SETTINGS
C<new_verifier> and C<new_request> each take a list of settings, as
function won't also be described in the section on the module's
functions.
function won't also be described in the section on the module's
functions.
=item C<dir>
The directory CGI::Auth::Generic should use for its data storage.
=item C<dir>
The directory CGI::Auth::Generic should use for its data storage.
If you want users to be able to explicitly log out, you need to
provide a logout button, something like
If you want users to be able to explicitly log out, you need to
provide a logout button, something like
-C<< <input type="submit" name="caf_logout" ...>>
+C<< <input type="submit" name="caf_logout" ... >>
The default is C<['caf_logout']>
The default is C<['caf_logout']>
=item C<< get_url($cgi,$authreq) >>
Hook which returns the URL of this web application. By default, we
=item C<< get_url($cgi,$authreq) >>
Hook which returns the URL of this web application. By default, we
Returns the HTTP method as a string. The default is to call
C<< $cgi->request_method() >>.
Returns the HTTP method as a string. The default is to call
C<< $cgi->request_method() >>.
=item C<< is_https($cgi,$authreq) >>
Returns a boolean indicating whether the request was over an encrypted
=item C<< is_https($cgi,$authreq) >>
Returns a boolean indicating whether the request was over an encrypted
Some of CAF's HTML-generating functions need to invent form parameter
names. They will all start with this string. Default: C<caf__>.
Some of CAF's HTML-generating functions need to invent form parameter
names. They will all start with this string. Default: C<caf__>.
=head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY
=over
=head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY
=over
xxx document @default_db_setup_statements
xxx bugs wrong default random on Linux
xxx document @default_db_setup_statements
xxx bugs wrong default random on Linux
xxx bugs wrong default random on *BSD
xxx bugs wrong default random on *BSD
xxx bugs keys not shared should be in db
xxx bugs keys not shared should be in db
xxx rename caf_assocsecret default cookie name
xxx rename caf_assocsecret default cookie name
xxx mention relationship between login_timeout and cookies
xxx mention relationship between login_timeout and cookies
~ian / cgi-auth-flexible.git / commitdiff