chiark / gitweb /
docs: move into separate file
[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 MUTATING OPERATIONS AND EXTERNAL LINKS INTO YOUR SITE
89
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.  
96
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.
102
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() >>
107 will call C<die>.
108
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.
111
112 =head2 DATA STORAGE
113
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.
116
117 =head1 SOURCE CODE DOWNLOAD
118
119 By default, CGI::Auth::Flexible provides a facility for users to
120 download the source code for the running version of your web
121 application.
122
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.
128
129 Here are the most important (default) assumptions:
130
131 =over
132
133 =item *
134
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.
139
140 =item *
141
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
146 library exceptio.)
147
148 =item *
149
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>.
153
154 =item *
155
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.
160
161 =item *
162
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>.
166
167 =item *
168
169 You have none of your app's source code in C</etc>.
170
171 =item *
172
173 You don't regard pathnames on your server as secret.
174
175 =item *
176
177 You don't intentionally load Perl code by virtule of C<.>
178 being in C<@INC> by default.  (See C<srcdump_filter_cwd>.)
179
180 =back
181
182 =head1 MAIN FUNCTIONS AND METHODS
183
184 =over
185
186 =item C<< CGI::Auth::Flexible->new_verifier(setting => value, ...) >>
187
188 Initialises an instance and returns a verifier object.
189 The arguments are setting pairs like a hash initialiser.
190 See L</SETTINGS> below.
191
192 =item C<< $verifier->new_request($cgi_query) >>
193
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.
199
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.
203
204 =item C<< $authreq->check_divert() >>
205
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.
209
210 This method may die if it doesn't like the request, in which case
211 the request needs to be rejected.
212
213 =item C<< $authreq->check_ok() >>
214
215 Checks whether the user is logged in.  Returns true if the user is
216 logged in and we should service the request.
217
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.
221
222 =item C<< $verifier->disconnect() >>
223
224 Discards the resources (open files, etc.) in the verifier object.
225
226 =back