chiark / gitweb /
javascript hijacking fix, docs are still wip
[cgi-auth-flexible.git] / 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