3 CGI::Auth::Flexible - web authentication optionally using cookies
7 my $verifier = CGI::Auth::Flexible->new_verifier(setting => value,...);
8 my $authreq = $verifier->new_request($cgi_query_object);
11 $authreq->check_ok() or return;
13 # sophisticated applications
14 my $divert_kind = $authreq->check_divert();
15 if ($divert_kind) { ... print diversion page and quit ... }
17 # while handling the request
18 $user = $authreq->get_username();
19 $authreq->check_mutate();
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.
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.
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.
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.
46 Your application should, on startup (eg, when it is loaded by
48 C<< $verifier = CGI::Auth::Flexible->new_verifier(settings...) >>.
49 This call can be expensive and is best amortised.
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) >>.
55 =head2 SIMPLE APPLICATIONS
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.
63 After calling C<check_ok> you can use C<< $request->get_username >>
64 to find out which user the request came from.
66 =head2 SOPHISTICATED APPLICATIONS
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.
74 =head2 GENERATING (MUTATING) FORMS AND AJAX QUERIES
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.
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.
86 Do not put the secret value in URLs for C<GET> requests.
88 =head2 MUTATING OPERATIONS AND EXTERNAL LINKS INTO YOUR SITE
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.
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.
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() >>
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.
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.
117 =head1 SOURCE CODE DOWNLOAD
119 By default, CGI::Auth::Flexible provides a facility for users to
120 download the source code for the running version of your web
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.
129 Here are the most important (default) assumptions:
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.
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
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>.
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.
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>.
169 You have none of your app's source code in C</etc>.
173 You don't regard pathnames on your server as secret.
177 You don't intentionally load Perl code by virtule of C<.>
178 being in C<@INC> by default. (See C<srcdump_filter_cwd>.)
182 =head1 MAIN FUNCTIONS AND METHODS
186 =item C<< CGI::Auth::Flexible->new_verifier(setting => value, ...) >>
188 Initialises an instance and returns a verifier object.
189 The arguments are setting pairs like a hash initialiser.
190 See L</SETTINGS> below.
192 =item C<< $verifier->new_request($cgi_query) >>
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.
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.
204 =item C<< $authreq->check_divert() >>
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.
210 This method may die if it doesn't like the request, in which case
211 the request needs to be rejected.
213 =item C<< $authreq->check_ok() >>
215 Checks whether the user is logged in. Returns true if the user is
216 logged in and we should service the request.
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.
222 =item C<< $verifier->disconnect() >>
224 Discards the resources (open files, etc.) in the verifier object.