Fix DBIC::Schema helper invocation examples (RT#100597)
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial / 05_Authentication.pod
2857be0d 1=head1 NAME
d442cc9f 2
3ab6187c 3Catalyst::Manual::Tutorial::05_Authentication - Catalyst Tutorial - Chapter 5: Authentication
d442cc9f 4
6=head1 OVERVIEW
4b4d3884 8This is B<Chapter 5 of 10> for the Catalyst tutorial.
d442cc9f 9
10L<Tutorial Overview|Catalyst::Manual::Tutorial>
12=over 4
14=item 1
3ab6187c 16L<Introduction|Catalyst::Manual::Tutorial::01_Intro>
d442cc9f 17
18=item 2
3ab6187c 20L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
d442cc9f 21
22=item 3
3ab6187c 24L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
d442cc9f 25
26=item 4
3ab6187c 28L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
d442cc9f 29
30=item 5
3ab6187c 32B<05_Authentication>
d442cc9f 33
34=item 6
3ab6187c 36L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
d442cc9f 37
38=item 7
3ab6187c 40L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>
d442cc9f 41
42=item 8
3ab6187c 44L<Testing|Catalyst::Manual::Tutorial::08_Testing>
d442cc9f 45
46=item 9
3ab6187c 48L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
d442cc9f 49
3533daff 50=item 10
d442cc9f 51
3ab6187c 52L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
d442cc9f 53
3533daff 54=back
2d0526d1 55
2d0526d1 56
d442cc9f 57=head1 DESCRIPTION
905a3a26 59Now that we finally have a simple yet functional application, we can
60focus on providing authentication (with authorization coming next in
e18d15c9 61L<Chapter 6|Catalyst::Manual::Tutorial::06_Authorization>).
d442cc9f 62
e18d15c9 63This chapter of the tutorial is divided into two main sections: 1)
64basic, cleartext authentication and 2) hash-based authentication.
d442cc9f 65
477a6d5b 66Source code for the tutorial in included in the F</home/catalyst/Final> directory
b1b6582a 67of the Tutorial Virtual machine (one subdirectory per chapter). There
68are also instructions for downloading the code in
2217b252 69L<Catalyst::Manual::Tutorial::01_Intro>.
d442cc9f 70
fbbb9084 71
d442cc9f 72=head1 BASIC AUTHENTICATION
74This section explores how to add authentication logic to a Catalyst
78=head2 Add Users and Roles to the Database
80First, we add both user and role information to the database (we will
81add the role information here although it will not be used until the
e18d15c9 82authorization section, Chapter 6). Create a new SQL script file by
83opening C<myapp02.sql> in your editor and insert:
d442cc9f 84
85 --
861a0cdd 86 -- Add users and role tables, along with a many-to-many join table
d442cc9f 87 --
3c700304 88 PRAGMA foreign_keys = ON;
861a0cdd 89 CREATE TABLE users (
d442cc9f 90 id INTEGER PRIMARY KEY,
91 username TEXT,
92 password TEXT,
93 email_address TEXT,
94 first_name TEXT,
95 last_name TEXT,
96 active INTEGER
97 );
3b1fa91b 98 CREATE TABLE role (
d442cc9f 99 id INTEGER PRIMARY KEY,
100 role TEXT
101 );
3b1fa91b 102 CREATE TABLE user_role (
d442cc9f 105 PRIMARY KEY (user_id, role_id)
106 );
107 --
108 -- Load up some initial test data
109 --
861a0cdd 110 INSERT INTO users VALUES (1, 'test01', 'mypass', '', 'Joe', 'Blow', 1);
111 INSERT INTO users VALUES (2, 'test02', 'mypass', '', 'Jane', 'Doe', 1);
112 INSERT INTO users VALUES (3, 'test03', 'mypass', '', 'No', 'Go', 0);
3b1fa91b 113 INSERT INTO role VALUES (1, 'user');
114 INSERT INTO role VALUES (2, 'admin');
115 INSERT INTO user_role VALUES (1, 1);
116 INSERT INTO user_role VALUES (1, 2);
117 INSERT INTO user_role VALUES (2, 1);
118 INSERT INTO user_role VALUES (3, 1);
d442cc9f 119
120Then load this into the C<myapp.db> database with the following command:
122 $ sqlite3 myapp.db < myapp02.sql
444d6b27 124
d442cc9f 125=head2 Add User and Role Information to DBIC Schema
3533daff 127Although we could manually edit the DBIC schema information to include
e18d15c9 128the new tables added in the previous step, let's use the
129C<create=static> option on the DBIC model helper to do most of the work
130for us:
d442cc9f 131
acbd7bdd 132 $ script/ model DB DBIC::Schema MyApp::Schema \
b6e53c1c 133 create=static components=TimeStamp dbi:SQLite:myapp.db \
b66dd084 134 on_connect_do="PRAGMA foreign_keys = ON"
477a6d5b 135 exists "/home/catalyst/dev/MyApp/script/../lib/MyApp/Model"
136 exists "/home/catalyst/dev/MyApp/script/../t"
137 Dumping manual schema for MyApp::Schema to directory /home/catalyst/dev/MyApp/script/../lib ...
1390ef0e 138 Schema dump completed.
477a6d5b 139 exists "/home/catalyst/dev/MyApp/script/../lib/MyApp/Model/"
1390ef0e 140 $
acbd7bdd 141 $ ls lib/MyApp/Schema/Result
3b1fa91b 142
d442cc9f 143
3c700304 144Notice how the helper has added three new table-specific Result Source
acbd7bdd 145files to the C<lib/MyApp/Schema/Result> directory. And, more
905a3a26 146importantly, even if there were changes to the existing result source
d8e9b469 147files, those changes would have only been written above the
148C<# DO NOT MODIFY THIS OR ANYTHING ABOVE!> comment and your hand-edited
3533daff 149enhancements would have been preserved.
d442cc9f 150
e18d15c9 151Speaking of "hand-edited enhancements," we should now add the
861a0cdd 152C<many_to_many> relationship information to the User Result Source file.
d8e9b469 153As with the Book, BookAuthor, and Author files in
154L<Chapter 3|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>,
e18d15c9 155L<DBIx::Class::Schema::Loader> has automatically created the C<has_many>
156and C<belongs_to> relationships for the new User, UserRole, and Role
157tables. However, as a convenience for mapping Users to their assigned
158roles (see L<Chapter 6|Catalyst::Manual::Tutorial::06_Authorization>),
159we will also manually add a C<many_to_many> relationship. Edit
861a0cdd 160C<lib/MyApp/Schema/Result/> add the following information between
161the C<# DO NOT MODIFY THIS OR ANYTHING ABOVE!> comment and the closing
d442cc9f 163
3533daff 164 # many_to_many():
165 # args:
166 # 1) Name of relationship, DBIC will create accessor with this name
905a3a26 167 # 2) Name of has_many() relationship this many_to_many() is shortcut for
168 # 3) Name of belongs_to() relationship in model class of has_many() above
3533daff 169 # You must already have the has_many() defined to use a many_to_many().
bd8f28e0 170 __PACKAGE__->many_to_many(roles => 'user_roles', 'role');
d442cc9f 171
861a0cdd 172The code for this update is obviously very similar to the edits we made
d8e9b469 173to the C<Book> and C<Author> classes created in
174L<Chapter 3|Catalyst::Manual::Tutorial::03_MoreCatalystBasics> with one
861a0cdd 175exception: we only defined the C<many_to_many> relationship in one
176direction. Whereas we felt that we would want to map Authors to Books
177B<AND> Books to Authors, here we are only adding the convenience
178C<many_to_many> in the Users to Roles direction.
3533daff 179
636ba9f7 180Note that we do not need to make any change to the
e18d15c9 181C<lib/MyApp/> schema file. It simply tells DBIC to load all of
d8e9b469 182the Result Class and ResultSet Class files it finds below the
e18d15c9 183C<lib/MyApp/Schema> directory, so it will automatically pick up our new
184table information.
d442cc9f 185
3c700304 187=head2 Sanity-Check of the Development Server Reload
d442cc9f 188
861a0cdd 189We aren't ready to try out the authentication just yet; we only want to
190do a quick check to be sure our model loads correctly. Assuming that you
191are following along and using the "-r" option on C<>,
192then the development server should automatically reload (if not, press
193C<Ctrl-C> to break out of the server if it's running and then enter
194C<script/> to start it). Look for the three new model
195objects in the startup debug output:
d442cc9f 196
197 ...
198 .-------------------------------------------------------------------+----------.
199 | Class | Type |
200 +-------------------------------------------------------------------+----------+
201 | MyApp::Controller::Books | instance |
202 | MyApp::Controller::Root | instance |
d0496197 203 | MyApp::Model::DB | instance |
204 | MyApp::Model::DB::Author | class |
3b1fa91b 205 | MyApp::Model::DB::Book | class |
206 | MyApp::Model::DB::BookAuthor | class |
207 | MyApp::Model::DB::Role | class |
208 | MyApp::Model::DB::User | class |
209 | MyApp::Model::DB::UserRole | class |
1edbdee6 210 | MyApp::View::HTML | instance |
d442cc9f 211 '-------------------------------------------------------------------+----------'
212 ...
e18d15c9 214Again, notice that your "Result Class" classes have been "re-loaded" by
215Catalyst under C<MyApp::Model>.
d442cc9f 216
218=head2 Include Authentication and Session Plugins
905a3a26 220Edit C<lib/> and update it as follows (everything below
3533daff 221C<StackTrace> is new):
d442cc9f 222
acbd7bdd 223 # Load plugins
2a6eb5f9 224 use Catalyst qw/
3c700304 225 -Debug
226 ConfigLoader
227 Static::Simple
8fefbef8 228
3c700304 229 StackTrace
8fefbef8 230
3c700304 231 Authentication
8fefbef8 232
3c700304 233 Session
95455c74 234 Session::Store::File
3c700304 235 Session::State::Cookie
236 /;
d442cc9f 237
d8e9b469 238B<Note:> As discussed in
239L<Chapter 3|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>,
240different versions of C<Catalyst::Devel> have used a variety of methods
241to load the plugins, but we are going to use the current Catalyst 5.9
242practice of putting them on the C<use Catalyst> line.
94d8da41 243
905a3a26 244The C<Authentication> plugin supports Authentication while the
245C<Session> plugins are required to maintain state across multiple HTTP
6d0971ad 247
905a3a26 248Note that the only required Authentication class is the main one. This
d8e9b469 249is a change that occurred in version 0.09999_01 of the
250L<Authentication|Catalyst::Plugin::Authentication> plugin. You
251B<do not need> to specify a particular
252L<Authentication::Store|Catalyst::Authentication::Store> or
253C<Authentication::Credential> you want to use. Instead, indicate the
254Store and Credential you want to use in your application configuration
255(see below).
6d0971ad 256
e18d15c9 257Make sure you include the additional plugins as new dependencies in the
258Makefile.PL file something like this:
3b1fa91b 259
e12f8011 260 requires 'Catalyst::Plugin::Authentication';
261 requires 'Catalyst::Plugin::Session';
95455c74 262 requires 'Catalyst::Plugin::Session::Store::File';
e12f8011 263 requires 'Catalyst::Plugin::Session::State::Cookie';
3b1fa91b 264
905a3a26 265Note that there are several options for
3c700304 266L<Session::Store|Catalyst::Plugin::Session::Store>.
e18d15c9 267L<Session::Store::Memcached|Catalyst::Plugin::Session::Store::Memcached>
268is generally a good choice if you are on Unix. If you are running on
269Windows L<Session::Store::File|Catalyst::Plugin::Session::Store::File>
270is fine. Consult L<Session::Store|Catalyst::Plugin::Session::Store> and
271its subclasses for additional information and options (for example to
d8e9b469 272use a database-backed session store).
d442cc9f 273
275=head2 Configure Authentication
3b1fa91b 277There are a variety of ways to provide configuration information to
e18d15c9 278L<Catalyst::Plugin::Authentication>. Here we will use
279L<Catalyst::Authentication::Realm::SimpleDB> because it automatically
d8e9b469 280sets a reasonable set of defaults for us. (Note: the C<SimpleDB> here
281has nothing to do with the SimpleDB offered in Amazon's web services
282offerings -- here we are only talking about a "simple" way to use your
283DB as an authentication backend.) Open C<lib/> and place the
284following text above the call to C<__PACKAGE__-E<gt>setup();>:
efdaddec 285
286 # Configure SimpleDB Authentication
19a5b486 287 __PACKAGE__->config(
288 'Plugin::Authentication' => {
efdaddec 289 default => {
290 class => 'SimpleDB',
3b1fa91b 291 user_model => 'DB::User',
efdaddec 292 password_type => 'clear',
293 },
19a5b486 294 },
295 );
efdaddec 296
e18d15c9 297We could have placed this configuration in C<myapp.conf>, but placing it
298in C<lib/> is probably a better place since it's not likely
861a0cdd 299something that users of your application will want to change during
e18d15c9 300deployment (or you could use a mixture: leave C<class> and C<user_model>
301defined in C<lib/> as we show above, but place C<password_type>
302in C<myapp.conf> to allow the type of password to be easily modified
303during deployment). We will stick with putting all of the
304authentication-related configuration in C<lib/> for the
305tutorial, but if you wish to use C<myapp.conf>, just convert to the
306following code:
c3cf3bc3 307
308 <Plugin::Authentication>
c3cf3bc3 309 <default>
43707053 310 password_type clear
3b1fa91b 311 user_model DB::User
c3cf3bc3 312 class SimpleDB
313 </default>
314 </Plugin::Authentication>
861a0cdd 316B<TIP:> Here is a short script that will dump the contents of
e18d15c9 317C<MyApp->config> to L<Config::General> format in C<myapp.conf>:
c3cf3bc3 318
861a0cdd 319 $ CATALYST_DEBUG=0 perl -Ilib -e 'use MyApp; use Config::General;
c3cf3bc3 320 Config::General->new->save_file("myapp.conf", MyApp->config);'
d442cc9f 321
3c700304 322B<HOWEVER>, if you try out the command above, be sure to delete the
323"myapp.conf" command. Otherwise, you will wind up with duplicate
d8e9b469 326B<NOTE:> Because we are using
89a65964 327L<SimpleDB|Catalyst::Authentication::Realm::SimpleDB> along with a
d8e9b469 328database layout that complies with its default assumptions: we don't
329need to specify the names of the columns where our username and password
330information is stored (hence, the "Simple" part of "SimpleDB"). That
331being said, SimpleDB lets you specify that type of information if you
332need to. Take a look at C<Catalyst::Authentication::Realm::SimpleDB>
c4fa597d 333for details.
1390ef0e 335
d442cc9f 336=head2 Add Login and Logout Controllers
fa59770d 338Use the Catalyst create script to create two stub controller files:
d442cc9f 339
fa59770d 340 $ script/ controller Login
341 $ script/ controller Logout
d442cc9f 342
fa59770d 343You could easily use a single controller here. For example, you could
344have a C<User> controller with both C<login> and C<logout> actions.
636ba9f7 345Remember, Catalyst is designed to be very flexible, and leaves such
fbbb9084 346matters up to you, the designer and programmer.
d442cc9f 347
d8e9b469 348Then open C<lib/MyApp/Controller/>, and update the definition of
349C<sub index> to match:
d442cc9f 350
fa59770d 351 =head2 index
8fefbef8 352
d442cc9f 353 Login logic
8fefbef8 354
d442cc9f 355 =cut
8fefbef8 356
fa59770d 357 sub index :Path :Args(0) {
d442cc9f 358 my ($self, $c) = @_;
8fefbef8 359
d442cc9f 360 # Get the username and password from form
ab0bd0bb 361 my $username = $c->request->params->{username};
362 my $password = $c->request->params->{password};
8fefbef8 363
d442cc9f 364 # If the username and password values were found in form
ab0bd0bb 365 if ($username && $password) {
d442cc9f 366 # Attempt to log the user in
905a3a26 367 if ($c->authenticate({ username => $username,
5fefca35 368 password => $password } )) {
d442cc9f 369 # If successful, then let them use the application
0416017e 370 $c->response->redirect($c->uri_for(
371 $c->controller('Books')->action_for('list')));
fa59770d 372 return;
d442cc9f 373 } else {
fa59770d 374 # Set an error message
0ed3df53 375 $c->stash(error_msg => "Bad username or password.");
d442cc9f 376 }
ab0bd0bb 377 } else {
fa59770d 378 # Set an error message
b6ff4050 379 $c->stash(error_msg => "Empty username or password.")
380 unless ($c->user_exists);
d442cc9f 381 }
8fefbef8 382
d442cc9f 383 # If either of above don't work out, send to the login page
0ed3df53 384 $c->stash(template => 'login.tt2');
d442cc9f 385 }
387This controller fetches the C<username> and C<password> values from the
905a3a26 388login form and attempts to authenticate the user. If successful, it
389redirects the user to the book list page. If the login fails, the user
390will stay at the login page and receive an error message. If the
e18d15c9 391C<username> and C<password> values are not present in the form, the user
392will be taken to the empty login form.
d442cc9f 393
636ba9f7 394Note that we could have used something like "C<sub default :Path>",
e18d15c9 395however, it is generally recommended (partly for historical reasons, and
396partly for code clarity) only to use C<default> in
636ba9f7 397C<MyApp::Controller::Root>, and then mainly to generate the 404 not
85d49fb6 398found page for the application.
ae492862 399
fa59770d 400Instead, we are using "C<sub somename :Path :Args(0) {...}>" here to
401specifically match the URL C</login>. C<Path> actions (aka, "literal
e18d15c9 402actions") create URI matches relative to the namespace of the controller
403where they are defined. Although C<Path> supports arguments that allow
404relative and absolute paths to be defined, here we use an empty C<Path>
405definition to match on just the name of the controller itself. The
406method name, C<index>, is arbitrary. We make the match even more
407specific with the C<:Args(0)> action modifier -- this forces the match
408on I<only> C</login>, not C</login/somethingelse>.
d442cc9f 409
905a3a26 410Next, update the corresponding method in
3533daff 411C<lib/MyApp/Controller/> to match:
d442cc9f 412
413 =head2 index
8fefbef8 414
d442cc9f 415 Logout logic
8fefbef8 416
d442cc9f 417 =cut
8fefbef8 418
ae492862 419 sub index :Path :Args(0) {
d442cc9f 420 my ($self, $c) = @_;
8fefbef8 421
d442cc9f 422 # Clear the user's state
423 $c->logout;
8fefbef8 424
d442cc9f 425 # Send the user to the starting point
426 $c->response->redirect($c->uri_for('/'));
427 }
d442cc9f 429
430=head2 Add a Login Form TT Template Page
432Create a login form by opening C<root/src/login.tt2> and inserting:
434 [% META title = 'Login' %]
8fefbef8 435
d442cc9f 436 <!-- Login form -->
8a7c5151 437 <form method="post" action="[% c.uri_for('/login') %]">
d442cc9f 438 <table>
439 <tr>
440 <td>Username:</td>
441 <td><input type="text" name="username" size="40" /></td>
442 </tr>
443 <tr>
444 <td>Password:</td>
445 <td><input type="password" name="password" size="40" /></td>
446 </tr>
447 <tr>
448 <td colspan="2"><input type="submit" name="submit" value="Submit" /></td>
449 </tr>
450 </table>
451 </form>
454=head2 Add Valid User Check
456We need something that provides enforcement for the authentication
457mechanism -- a I<global> mechanism that prevents users who have not
458passed authentication from reaching any pages except the login page.
861a0cdd 459This is generally done via an C<auto> action/method in
444d6b27 460C<lib/MyApp/Controller/>.
d442cc9f 461
462Edit the existing C<lib/MyApp/Controller/> class file and insert
463the following method:
465 =head2 auto
8fefbef8 466
d442cc9f 467 Check if there is a user and, if not, forward to login page
8fefbef8 468
d442cc9f 469 =cut
8fefbef8 470
d442cc9f 471 # Note that 'auto' runs after 'begin' but before your actions and that
905a3a26 472 # 'auto's "chain" (all from application path to most specific class are run)
d442cc9f 473 # See the 'Actions' section of 'Catalyst::Manual::Intro' for more info.
ddfbd850 474 sub auto :Private {
d442cc9f 475 my ($self, $c) = @_;
8fefbef8 476
d442cc9f 477 # Allow unauthenticated users to reach the login page. This
191dee29 478 # allows unauthenticated users to reach any action in the Login
d442cc9f 479 # controller. To lock it down to a single action, we could use:
480 # if ($c->action eq $c->controller('Login')->action_for('index'))
905a3a26 481 # to only allow unauthenticated access to the 'index' action we
d442cc9f 482 # added above.
483 if ($c->controller eq $c->controller('Login')) {
484 return 1;
485 }
8fefbef8 486
d442cc9f 487 # If a user doesn't exist, force login
488 if (!$c->user_exists) {
489 # Dump a log message to the development server debug output
490 $c->log->debug('***Root::auto User not found, forwarding to /login');
491 # Redirect the user to the login page
492 $c->response->redirect($c->uri_for('/login'));
493 # Return 0 to cancel 'post-auto' processing and prevent use of application
494 return 0;
495 }
8fefbef8 496
d442cc9f 497 # User found, so return 1 to continue with processing after this 'auto'
498 return 1;
499 }
636ba9f7 501As discussed in
3ab6187c 502L<Catalyst::Manual::Tutorial::03_MoreCatalystBasics/CREATE A CATALYST CONTROLLER>,
636ba9f7 503every C<auto> method from the application/root controller down to the
e18d15c9 504most specific controller will be called. By placing the authentication
505enforcement code inside the C<auto> method of
506C<lib/MyApp/Controller/> (or C<lib/>), it will be called
507for I<every> request that is received by the entire application.
d442cc9f 508
510=head2 Displaying Content Only to Authenticated Users
512Let's say you want to provide some information on the login page that
513changes depending on whether the user has authenticated yet. To do
514this, open C<root/src/login.tt2> in your editor and add the following
515lines to the bottom of the file:
acbd7bdd 517 ...
d442cc9f 518 <p>
519 [%
905a3a26 520 # This code illustrates how certain parts of the TT
d442cc9f 521 # template will only be shown to users who have logged in
522 %]
8a7c5151 523 [% IF c.user_exists %]
524 Please Note: You are already logged in as '[% c.user.username %]'.
525 You can <a href="[% c.uri_for('/logout') %]">logout</a> here.
d442cc9f 526 [% ELSE %]
527 You need to log in to use this application.
528 [% END %]
529 [%#
530 Note that this whole block is a comment because the "#" appears
905a3a26 531 immediate after the "[%" (with no spaces in between). Although it
532 can be a handy way to temporarily "comment out" a whole block of
533 TT code, it's probably a little too subtle for use in "normal"
d442cc9f 534 comments.
535 %]
3533daff 536 </p>
d442cc9f 537
538Although most of the code is comments, the middle few lines provide a
539"you are already logged in" reminder if the user returns to the login
540page after they have already authenticated. For users who have not yet
541authenticated, a "You need to log in..." message is displayed (note the
542use of an IF-THEN-ELSE construct in TT).
545=head2 Try Out Authentication
861a0cdd 547The development server should have reloaded each time we edited one of
3e1a2240 548the Controllers in the previous section. Now try going to
861a0cdd 549L<http://localhost:3000/books/list> and you should be redirected to the
550login page, hitting Shift+Reload or Ctrl+Reload if necessary (the "You
551are already logged in" message should I<not> appear -- if it does, click
552the C<logout> button and try again). Note the C<***Root::auto User not
553found...> debug message in the development server output. Enter username
554C<test01> and password C<mypass>, and you should be taken to the Book
555List page.
d442cc9f 556
636ba9f7 557B<IMPORTANT NOTE:> If you are having issues with authentication on
d8e9b469 558Internet Explorer (or potentially other browsers), be sure to check the
559system clocks on both your server and client machines. Internet
560Explorer is very picky about timestamps for cookies. You can use the
561C<ntpq -p> command on the Tutorial Virtual Machine to check time sync
562and/or use the following command to force a sync:
25ed8f40 563
acbd7bdd 564 sudo ntpdate-debian
d442cc9f 565
d8e9b469 566Or, depending on your firewall configuration, try it with "-u":
acbd7bdd 567
568 sudo ntpdate-debian -u
636ba9f7 570Note: NTP can be a little more finicky about firewalls because it uses
acbd7bdd 571UDP vs. the more common TCP that you see with most Internet protocols.
572Worse case, you might have to manually set the time on your development
573box instead of using NTP.
1390ef0e 574
d442cc9f 575Open C<root/src/books/list.tt2> and add the following lines to the
3533daff 576bottom (below the closing </table> tag):
d442cc9f 577
aa7ff325 578 ...
d442cc9f 579 <p>
8a7c5151 580 <a href="[% c.uri_for('/login') %]">Login</a>
0416017e 581 <a href="[% c.uri_for(c.controller.action_for('form_create')) %]">Create</a>
d442cc9f 582 </p>
905a3a26 584Reload your browser and you should now see a "Login" and "Create" links
585at the bottom of the page (as mentioned earlier, you can update template
e18d15c9 586files without a development server reload). Click the first link to
587return to the login page. This time you I<should> see the "You are
d442cc9f 588already logged in" message.
590Finally, click the C<You can logout here> link on the C</login> page.
591You should stay at the login page, but the message should change to "You
592need to log in to use this application."
861a0cdd 597In this section we increase the security of our system by converting
e18d15c9 598from cleartext passwords to SHA-1 password hashes that include a random
d8e9b469 599"salt" value to make them extremely difficult to crack, even with
600dictionary and "rainbow table" attacks.
d442cc9f 601
602B<Note:> This section is optional. You can skip it and the rest of the
603tutorial will function normally.
e18d15c9 605Be aware that even with the techniques shown in this section, the
606browser still transmits the passwords in cleartext to your application.
607We are just avoiding the I<storage> of cleartext passwords in the
608database by using a salted SHA-1 hash. If you are concerned about
609cleartext passwords between the browser and your application, consider
d8e9b469 610using SSL/TLS, made easy with modules such as
611L<Catalyst::Plugin:RequireSSL> and L<Catalyst::ActionRole::RequireSSL>.
d442cc9f 612
436f45da 614=head2 Re-Run the DBIC::Schema Model Helper to Include DBIx::Class::PassphraseColumn
d442cc9f 615
d8e9b469 616Let's re-run the model helper to have it include
e18d15c9 617L<DBIx::Class::PassphraseColumn> in all of the Result Classes it
618generates for us. Simply use the same command we saw in Chapters 3 and
6194, but add C<,PassphraseColumn> to the C<components> argument:
d442cc9f 620
efdaddec 621 $ script/ model DB DBIC::Schema MyApp::Schema \
b6e53c1c 622 create=static components=TimeStamp,PassphraseColumn dbi:SQLite:myapp.db \
b66dd084 623 on_connect_do="PRAGMA foreign_keys = ON"
d442cc9f 624
861a0cdd 625If you then open one of the Result Classes, you will see that it
e18d15c9 626includes PassphraseColumn in the C<load_components> line. Take a look
627at C<lib/MyApp/Schema/Result/> since that's the main class where
628we want to use hashed and salted passwords:
efdaddec 629
436f45da 630 __PACKAGE__->load_components("InflateColumn::DateTime", "TimeStamp", "PassphraseColumn");
efdaddec 631
436f45da 633=head2 Modify the "password" Column to Use PassphraseColumn
efdaddec 634
3b1fa91b 635Open the file C<lib/MyApp/Schema/Result/> and enter the following
efdaddec 636text below the "# DO NOT MODIFY THIS OR ANYTHING ABOVE!" line but above
637the closing "1;":
436f45da 639 # Have the 'password' column use a SHA-1 hash and 20-byte salt
640 # with RFC 2307 encoding; Generate the 'check_password" method
efdaddec 641 __PACKAGE__->add_columns(
642 'password' => {
436f45da 643 passphrase => 'rfc2307',
644 passphrase_class => 'SaltedDigest',
645 passphrase_args => {
646 algorithm => 'SHA-1',
647 salt_random => 20.
648 },
649 passphrase_check_method => 'check_password',
efdaddec 650 },
651 );
e18d15c9 653This redefines the automatically generated definition for the password
654fields at the top of the Result Class file to now use PassphraseColumn
655logic, storing passwords in RFC 2307 format (C<passphrase> is set to
656C<rfc2307>). C<passphrase_class> can be set to the name of any
657C<Authen::Passphrase::*> class, such as C<SaltedDigest> to use
658L<Authen::Passphrase::SaltedDigest>, or C<BlowfishCrypt> to use
659L<Authen::Passphrase::BlowfishCrypt>. C<passphrase_args> is then used
660to customize the passphrase class you selected. Here we specified the
661digest algorithm to use as C<SHA-1> and the size of the salt to use, but
662we could have also specified any other option the selected passphrase
663class supports.
efdaddec 665
666=head2 Load Hashed Passwords in the Database
e18d15c9 668Next, let's create a quick script to load some hashed and salted
669passwords into the C<password> column of our C<users> table. Open the
670file C<> in your editor and enter the following
efdaddec 672
673 #!/usr/bin/perl
8fefbef8 674
efdaddec 675 use strict;
676 use warnings;
8fefbef8 677
efdaddec 678 use MyApp::Schema;
8fefbef8 679
efdaddec 680 my $schema = MyApp::Schema->connect('dbi:SQLite:myapp.db');
8fefbef8 681
3b1fa91b 682 my @users = $schema->resultset('User')->all;
8fefbef8 683
efdaddec 684 foreach my $user (@users) {
685 $user->password('mypass');
686 $user->update;
687 }
436f45da 689PassphraseColumn lets us simply call C<$user->check_password($password)>
861a0cdd 690to see if the user has supplied the correct password, or, as we show
691above, call C<$user->update($new_password)> to update the hashed
efdaddec 692password stored for this user.
694Then run the following command:
2a6eb5f9 696 $ DBIC_TRACE=1 perl -Ilib
efdaddec 697
bd8f28e0 698We had to use the C<-Ilib> argument to tell Perl to look under the
efdaddec 699C<lib> directory for our C<MyApp::Schema> model.
2a6eb5f9 701The DBIC_TRACE output should show that the update worked:
703 $ DBIC_TRACE=1 perl -Ilib
861a0cdd 704 SELECT, me.username, me.password, me.email_address,
705 me.first_name, me.last_name, FROM users me:
706 UPDATE users SET password = ? WHERE ( id = ? ):
436f45da 707 '{SSHA}esgz64CpHMo8pMfgIIszP13ft23z/zio04aCwNdm0wc6MDeloMUH4g==', '1'
861a0cdd 708 UPDATE users SET password = ? WHERE ( id = ? ):
436f45da 709 '{SSHA}FpGhpCJus+Ea9ne4ww8404HH+hJKW/fW+bAv1v6FuRUy2G7I2aoTRQ==', '2'
861a0cdd 710 UPDATE users SET password = ? WHERE ( id = ? ):
436f45da 711 '{SSHA}ZyGlpiHls8qFBSbHr3r5t/iqcZE602XLMbkSVRRNl6rF8imv1abQVg==', '3'
2a6eb5f9 712
713But we can further confirm our actions by dumping the users table:
efdaddec 714
861a0cdd 715 $ sqlite3 myapp.db "select * from users"
436f45da 716 1|test01|{SSHA}esgz64CpHMo8pMfgIIszP13ft23z/zio04aCwNdm0wc6MDeloMUH4g==||Joe|Blow|1
717 2|test02|{SSHA}FpGhpCJus+Ea9ne4ww8404HH+hJKW/fW+bAv1v6FuRUy2G7I2aoTRQ==||Jane|Doe|1
718 3|test03|{SSHA}ZyGlpiHls8qFBSbHr3r5t/iqcZE602XLMbkSVRRNl6rF8imv1abQVg==||No|Go|0
efdaddec 719
e18d15c9 720As you can see, the passwords are much harder to steal from the database
721(not only are the hashes stored, but every hash is different even though
722the passwords are the same because of the added "salt" value). Also
723note that this demonstrates how to use a DBIx::Class model outside of
724your web application -- a very useful feature in many situations.
efdaddec 725
727=head2 Enable Hashed and Salted Passwords
d8e9b469 729Edit C<lib/> and update the config() section for
730C<Plugin::Authentication> it to match the following text (the only
e18d15c9 731change is to the C<password_type> field):
efdaddec 732
733 # Configure SimpleDB Authentication
19a5b486 734 __PACKAGE__->config(
735 'Plugin::Authentication' => {
efdaddec 736 default => {
737 class => 'SimpleDB',
3b1fa91b 738 user_model => 'DB::User',
efdaddec 739 password_type => 'self_check',
740 },
19a5b486 741 },
742 );
efdaddec 743
861a0cdd 744The use of C<self_check> will cause
9c5abba4 745Catalyst::Plugin::Authentication::Store::DBIx::Class to call the
efdaddec 746C<check_password> method we enabled on our C<password> columns.
d442cc9f 747
1390ef0e 748
d442cc9f 749=head2 Try Out the Hashed Passwords
861a0cdd 751The development server should restart as soon as your save the
752C<lib/> file in the previous section. You should now be able to
753go to L<http://localhost:3000/books/list> and login as before. When
754done, click the "logout" link on the login page (or point your browser
755at L<http://localhost:3000/logout>).
d442cc9f 756
d442cc9f 757
861a0cdd 760As discussed in the previous chapter of the tutorial, C<flash> allows
761you to set variables in a way that is very similar to C<stash>, but it
e18d15c9 762will remain set across multiple requests. Once the value is read, it is
763cleared (unless reset). Although C<flash> has nothing to do with
861a0cdd 764authentication, it does leverage the same session plugins. Now that
765those plugins are enabled, let's go back and update the "delete and
e18d15c9 766redirect with query parameters" code seen at the end of the
767L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD> chapter of the
768tutorial to take advantage of C<flash>.
d442cc9f 769
e18d15c9 770First, open C<lib/MyApp/Controller/> and modify C<sub delete> to
771match the following (everything after the model search line of code has
d442cc9f 773
905a3a26 774 =head2 delete
8fefbef8 775
d442cc9f 776 Delete a book
8fefbef8 777
d442cc9f 778 =cut
8fefbef8 779
fbbb9084 780 sub delete :Chained('object') :PathPart('delete') :Args(0) {
781 my ($self, $c) = @_;
8fefbef8 782
fbbb9084 783 # Use the book object saved by 'object' and delete it along
784 # with related 'book_authors' entries
785 $c->stash->{object}->delete;
8fefbef8 786
d442cc9f 787 # Use 'flash' to save information across requests until it's read
788 $c->flash->{status_msg} = "Book deleted";
8fefbef8 789
3533daff 790 # Redirect the user back to the list page
0416017e 791 $c->response->redirect($c->uri_for($self->action_for('list')));
d442cc9f 792 }
1390ef0e 794Next, open C<root/src/wrapper.tt2> and update the TT code to pull from
d442cc9f 795flash vs. the C<status_msg> query parameter:
1390ef0e 797 ...
d442cc9f 798 <div id="content">
1390ef0e 799 [%# Status and error messages %]
800 <span class="message">[% status_msg || c.flash.status_msg %]</span>
801 <span class="error">[% error_msg %]</span>
802 [%# This is where TT will stick all of your template's contents. -%]
803 [% content %]
804 </div><!-- end content -->
805 ...
905a3a26 806
e18d15c9 807Although the sample above only shows the C<content> div, leave the rest
808of the file intact -- the only change we made to replace "||
809c.request.params.status_msg" with "c.flash.status_msg" in the
810C<E<lt>span class="message"E<gt>> line.
d442cc9f 811
813=head2 Try Out Flash
3c700304 815Authenticate using the login screen and then point your browser to
636ba9f7 816L<http://localhost:3000/books/url_create/Test/1/4> to create an extra
817several books. Click the "Return to list" link and delete one of the
818"Test" books you just added. The C<flash> mechanism should retain our
3533daff 819"Book deleted" status message across the redirect.
d442cc9f 820
821B<NOTE:> While C<flash> will save information across multiple requests,
822I<it does get cleared the first time it is read>. In general, this is
e18d15c9 823exactly what you want -- the C<flash> message will get displayed on the
824next screen where it's appropriate, but it won't "keep showing up" after
825that first time (unless you reset it). Please refer to
826L<Catalyst::Plugin::Session> for additional information.
d442cc9f 827
d8e9b469 828B<Note:> There is also a C<flash-to-stash> feature that will
829automatically load the contents the contents of flash into stash,
830allowing us to use the more typical C<c.flash.status_msg> in our TT
831template in lieu of the more verbose C<status_msg || c.flash.status_msg>
832we used above. Consult L<Catalyst::Plugin::Session> for additional
836=head2 Switch To Catalyst::Plugin::StatusMessages
838Although the query parameter technique we used in
839L<Chapter 4|Catalyst::Manual::Tutorial::04_BasicCRUD> and the C<flash>
840approach we used above will work in most cases, they both have their
841drawbacks. The query parameters can leave the status message on the
842screen longer than it should (for example, if the user hits refresh).
843And C<flash> can display the wrong message on the wrong screen (flash
844just shows the message on the next page for that user... if the user
845has multiple windows or tabs open, then the wrong one can get the
846status message).
848L<Catalyst::Plugin::StatusMessage> is designed to address these
849shortcomings. It stores the messages in the user's session (so they are
850available across multiple requests), but ties each status message to a
851random token. By passing this token across the redirect, we are no
852longer relying on a potentially ambiguous "next request" like we do with
853flash. And, because the message is deleted the first time it's
854displayed, the user can hit refresh and still only see the message a
855single time (even though the URL may continue to reference the token,
856it's only displayed the first time). The use of C<StatusMessage>
857or a similar mechanism is recommended for all Catalyst applications.
859To enable C<StatusMessage>, first edit C<lib/> and add
860C<StatusMessage> to the list of plugins:
1390ef0e 861
d8e9b469 862 use Catalyst qw/
863 -Debug
864 ConfigLoader
865 Static::Simple
3e29729b 867 StackTrace
d8e9b469 869 Authentication
871 Session
872 Session::Store::File
873 Session::State::Cookie
875 StatusMessage
876 /;
3533daff 877
d8e9b469 878Then edit C<lib/MyApp/Controller/> and modify the C<delete>
879action to match the following:
3533daff 880
d8e9b469 881 sub delete :Chained('object') :PathPart('delete') :Args(0) {
882 my ($self, $c) = @_;
884 # Saved the PK id for status_msg below
885 my $id = $c->stash->{object}->id;
887 # Use the book object saved by 'object' and delete it along
888 # with related 'book_authors' entries
889 $c->stash->{object}->delete;
891 # Redirect the user back to the list page
892 $c->response->redirect($c->uri_for($self->action_for('list'),
893 {mid => $c->set_status_msg("Deleted book $id")}));
894 }
896This uses the C<set_status_msg> that the plugin added to C<$c> to save
897the message under a random token. (If we wanted to save an error
898message, we could have used C<set_error_msg>.) Because
899C<set_status_msg> and C<set_error_msg> both return the random token, we
900can assign that value to the "C<mid>" query parameter via C<uri_for> as
901shown above.
903Next, we need to make sure that the list page will load display the
904message. The easiest way to do this is to take advantage of the chained
905dispatch we implemented in
906L<Chapter 4|Catalyst::Manual::Tutorial::04_BasicCRUD>. Edit
907C<lib/MyApp/Controller/> again and update the C<base> action to
910 sub base :Chained('/') :PathPart('books') :CaptureArgs(0) {
911 my ($self, $c) = @_;
913 # Store the ResultSet in stash so it's available for other methods
914 $c->stash(resultset => $c->model('DB::Book'));
916 # Print a message to the debug log
917 $c->log->debug('*** INSIDE BASE METHOD ***');
919 # Load status messages
920 $c->load_status_msgs;
921 }
3533daff 922
d8e9b469 923That way, anything that chains off C<base> will automatically get any
924status or error messages loaded into the stash. Let's convert the
925C<list> action to take advantage of this. Modify the method signature
926for C<list> from:
3533daff 927
d8e9b469 928 sub list :Local {
3533daff 929
d8e9b469 930to:
3533daff 931
8f19d4dd 932 sub list :Chained('base') :PathPart('list') :Args(0) {
3533daff 933
d8e9b469 934Finally, let's clean up the status/error message code in our wrapper
935template. Edit C<root/src/wrapper.tt2> and change the "content" div
936to match the following:
938 <div id="content">
939 [%# Status and error messages %]
940 <span class="message">[% status_msg %]</span>
941 <span class="error">[% error_msg %]</span>
942 [%# This is where TT will stick all of your template's contents. -%]
943 [% content %]
944 </div><!-- end content -->
3533daff 945
861a0cdd 946Now go to L<http://localhost:3000/books/list> in your browser. Delete
d8e9b469 947another of the "Test" books you added in the previous step. You should
948get redirection from the C<delete> action back to the C<list> action,
949but with a "mid=########" message ID query parameter. The screen should
950say "Deleted book #" (where # is the PK id of the book you removed).
951However, if you hit refresh in your browser, the status message is no
952longer displayed (even though the URL does still contain the message ID
953token, it is ignored -- thereby keeping the state of our status/error
954messages in sync with the users actions).
3533daff 955
d442cc9f 956
24acc5d7 957You can jump to the next chapter of the tutorial here:
d442cc9f 961=head1 AUTHOR
963Kennedy Clark, C<>
53243324 965Feel free to contact the author for any errors or suggestions, but the
966best way to report issues is via the CPAN RT Bug system at
bb0999d3 967L<>.
53243324 968
bb0999d3 969Copyright 2006-2011, Kennedy Clark, under the
ec3ef4ad 970Creative Commons Attribution Share-Alike License Version 3.0
95674086 971(L<>).