From: Ian Jackson Date: Wed, 28 Oct 2015 16:19:28 +0000 (+0000) Subject: Docs: Various fixes and minor clarifications X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=cgi-auth-flexible.git;a=commitdiff_plain;h=cdb13789e4025ebc1ab10ce6784ffad7a222a35a;ds=sidebyside Docs: Various fixes and minor clarifications Signed-off-by: Ian Jackson --- diff --git a/caf.pod b/caf.pod index fcb0615..ab45ac0 100644 --- a/caf.pod +++ b/caf.pod @@ -133,10 +133,10 @@ interfaces for this: =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 -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 @@ -145,13 +145,15 @@ C. After C 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 and/or C +- 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 -the user is logged in, or I if some kind of login +the user is logged in, or a I if some kind of login page or diversion should be generated. See L below for details of how to deal with the return value. @@ -159,16 +161,19 @@ details of how to deal with the return value. =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 -use C. This restriction arises from complicated deficiencies -in the web's security architecture. +use C. 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 @@ -198,7 +203,7 @@ include a secret hidden form parameter for the benefit of CGI::Auth::Generic. This form parameter will be checked by C/C and should be ignored by your application. -By default the hidden parameter is called C. +By default the hidden parameter is called C. After calling C or C the value to put in your form can be obtained from C; C @@ -373,6 +378,8 @@ All of these are only valid after C or C has been called. (In the case of C it won't normally be sensible to call these functions unless C returned true.) +=over + =item C<< $authreq->get_divert() >> Returns the value previously returned by C. @@ -413,8 +420,12 @@ C will either return successfully, indicating that all is well and the request should proceed, or it will die, like C. +=back + =head1 RESPONSE-RELATED FUNCTIONS AND METHODS +=over + =item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >> Convenience function which returns a url for a GET request to this @@ -462,7 +473,7 @@ Returns the value of the secret cookie. CGI::Auth::Flexible sets this cookie in the forms generated by C. You may also set it yourself (and indeed you must do so if you use C). -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. This is all of the query @@ -490,7 +501,7 @@ parameter. I<$reqtype> is the request type (the value which will be passed to C and C. 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 @@ -603,7 +614,7 @@ confidential for the user.) C<< XMLHttpRequest >> returning data of some other kind. (Possibly confidential for the user.) -=back. +=back =head1 DIVERT SPEC @@ -633,6 +644,10 @@ should be sent; C<''> means the cookie should be cleared. =item C +Provided with diversion kinds which involve +generating a redirection or indirection, +perhaps via a login form. + The extra hidden form parameters (and the C) which should be set when the subsequent request bounces back from the client, in the form used by C. @@ -722,6 +737,8 @@ submits our own main page without any parameters. (Applications which set C do not see this divert kind.) +=back + =head1 SETTINGS C and C each take a list of settings, as @@ -748,10 +765,10 @@ When a hook's default implementation is mentioned and named, that function won't also be described in the section on the module's functions. -=over - =head2 GENERAL SETTINGS +=over + =item C The directory CGI::Auth::Generic should use for its data storage. @@ -881,7 +898,7 @@ Used by the default C hook. If you want users to be able to explicitly log out, you need to provide a logout button, something like -C<< > +C<< > The default is C<['caf_logout']> @@ -914,8 +931,6 @@ only flag on its cookie. The default is 1. -=back - =item C<< get_url($cgi,$authreq) >> Hook which returns the URL of this web application. By default, we @@ -974,8 +989,6 @@ value of the cookie. Returns the HTTP method as a string. The default is to call C<< $cgi->request_method() >>. -=back - =item C<< is_https($cgi,$authreq) >> Returns a boolean indicating whether the request was over an encrypted @@ -1087,6 +1100,8 @@ Size of generated text entry fields. Default is 60. Some of CAF's HTML-generating functions need to invent form parameter names. They will all start with this string. Default: C. +=back + =head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY =over @@ -1353,7 +1368,11 @@ xxx document construct_cookie fn xxx document @default_db_setup_statements xxx bugs wrong default random on Linux + xxx bugs wrong default random on *BSD + xxx bugs keys not shared should be in db + xxx rename caf_assocsecret default cookie name + xxx mention relationship between login_timeout and cookies