Merge from depluralization branch
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial / Authentication.pod
d442cc9f 1=head1 NAME
4b4d3884 3Catalyst::Manual::Tutorial::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
18=item 2
20L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
22=item 3
3533daff 24L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
d442cc9f 25
26=item 4
3533daff 28L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
d442cc9f 29
30=item 5
3533daff 32B<Authentication>
d442cc9f 33
34=item 6
3533daff 36L<Authorization|Catalyst::Manual::Tutorial::Authorization>
d442cc9f 37
38=item 7
3533daff 40L<Debugging|Catalyst::Manual::Tutorial::Debugging>
d442cc9f 41
42=item 8
3533daff 44L<Testing|Catalyst::Manual::Tutorial::Testing>
d442cc9f 45
46=item 9
3533daff 48L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
d442cc9f 49
3533daff 50=item 10
d442cc9f 51
3533daff 52L<Appendices|Catalyst::Manual::Tutorial::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
4b4d3884 61Chapter 6).
d442cc9f 62
4b4d3884 63This chapter of the tutorial is divided into two main sections: 1) basic,
d442cc9f 64cleartext authentication and 2) hash-based authentication.
66You can checkout the source code for this example from the catalyst
67subversion repository as per the instructions in
1390ef0e 68L<Catalyst::Manual::Tutorial::Intro|Catalyst::Manual::Tutorial::Intro>.
d442cc9f 69
fbbb9084 70
d442cc9f 71=head1 BASIC AUTHENTICATION
73This section explores how to add authentication logic to a Catalyst
77=head2 Add Users and Roles to the Database
79First, we add both user and role information to the database (we will
80add the role information here although it will not be used until the
4b4d3884 81authorization section, Chapter 6). Create a new SQL script file by opening
d442cc9f 82C<myapp02.sql> in your editor and insert:
84 --
3b1fa91b 85 -- Add user and role tables, along with a many-to-many join table
d442cc9f 86 --
3b1fa91b 87 CREATE TABLE user (
d442cc9f 88 id INTEGER PRIMARY KEY,
89 username TEXT,
90 password TEXT,
91 email_address TEXT,
92 first_name TEXT,
93 last_name TEXT,
94 active INTEGER
95 );
3b1fa91b 96 CREATE TABLE role (
d442cc9f 97 id INTEGER PRIMARY KEY,
98 role TEXT
99 );
3b1fa91b 100 CREATE TABLE user_role (
d442cc9f 101 user_id INTEGER,
102 role_id INTEGER,
103 PRIMARY KEY (user_id, role_id)
104 );
105 --
106 -- Load up some initial test data
107 --
3b1fa91b 108 INSERT INTO user VALUES (1, 'test01', 'mypass', '', 'Joe', 'Blow', 1);
109 INSERT INTO user VALUES (2, 'test02', 'mypass', '', 'Jane', 'Doe', 1);
110 INSERT INTO user VALUES (3, 'test03', 'mypass', '', 'No', 'Go', 0);
111 INSERT INTO role VALUES (1, 'user');
112 INSERT INTO role VALUES (2, 'admin');
113 INSERT INTO user_role VALUES (1, 1);
114 INSERT INTO user_role VALUES (1, 2);
115 INSERT INTO user_role VALUES (2, 1);
116 INSERT INTO user_role VALUES (3, 1);
d442cc9f 117
118Then load this into the C<myapp.db> database with the following command:
120 $ sqlite3 myapp.db < myapp02.sql
d442cc9f 122=head2 Add User and Role Information to DBIC Schema
3533daff 124Although we could manually edit the DBIC schema information to include
125the new tables added in the previous step, let's use the C<create=static>
126option on the DBIC model helper to do most of the work for us:
d442cc9f 127
acbd7bdd 128 $ script/ model DB DBIC::Schema MyApp::Schema \
129 create=static components=TimeStamp dbi:SQLite:myapp.db
1390ef0e 130 exists "/root/dev/MyApp/script/../lib/MyApp/Model"
131 exists "/root/dev/MyApp/script/../t"
132 Dumping manual schema for MyApp::Schema to directory /root/dev/MyApp/script/../lib ...
133 Schema dump completed.
134 exists "/root/dev/MyApp/script/../lib/MyApp/Model/"
135 $
acbd7bdd 136 $ ls lib/MyApp/Schema/Result
3b1fa91b 137
d442cc9f 138
905a3a26 139Notice how the helper has added three new table-specific result source
acbd7bdd 140files to the C<lib/MyApp/Schema/Result> directory. And, more
905a3a26 141importantly, even if there were changes to the existing result source
142files, those changes would have only been written above the C<# DO NOT
191dee29 143MODIFY THIS OR ANYTHING ABOVE!> comment and your hand-edited
3533daff 144enhancements would have been preserved.
d442cc9f 145
3b1fa91b 146Speaking of "hand-editted enhancements," we should now add
905a3a26 147relationship information to the three new result source files. Edit
148each of these files and add the following information between the C<#
3533daff 149DO NOT MODIFY THIS OR ANYTHING ABOVE!> comment and the closing C<1;>:
d442cc9f 150
3b1fa91b 151C<lib/MyApp/Schema/Result/>:
d442cc9f 152
d442cc9f 153 #
154 # Set relationships:
155 #
efdaddec 156
d442cc9f 157 # has_many():
158 # args:
159 # 1) Name of relationship, DBIC will create accessor with this name
160 # 2) Name of the model class referenced by this relationship
1435672d 161 # 3) Column name in *foreign* table (aka, foreign key in peer table)
3b1fa91b 162 __PACKAGE__->has_many(map_user_role => 'MyApp::Schema::Result::UserRole', 'user_id');
efdaddec 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().
170 __PACKAGE__->many_to_many(roles => 'map_user_role', 'role');
d442cc9f 171
3b1fa91b 173C<lib/MyApp/Schema/Result/>:
d442cc9f 174
d442cc9f 175 #
176 # Set relationships:
177 #
efdaddec 178
d442cc9f 179 # has_many():
180 # args:
181 # 1) Name of relationship, DBIC will create accessor with this name
182 # 2) Name of the model class referenced by this relationship
1435672d 183 # 3) Column name in *foreign* table (aka, foreign key in peer table)
3b1fa91b 184 __PACKAGE__->has_many(map_user_role => 'MyApp::Schema::Result::UserRole', 'role_id');
d442cc9f 185
3b1fa91b 187C<lib/MyApp/Schema/Result/>:
d442cc9f 188
d442cc9f 189 #
190 # Set relationships:
191 #
efdaddec 192
d442cc9f 193 # belongs_to():
194 # args:
195 # 1) Name of relationship, DBIC will create accessor with this name
196 # 2) Name of the model class referenced by this relationship
197 # 3) Column name in *this* table
3b1fa91b 198 __PACKAGE__->belongs_to(user => 'MyApp::Schema::Result::User', 'user_id');
efdaddec 199
d442cc9f 200 # belongs_to():
201 # args:
202 # 1) Name of relationship, DBIC will create accessor with this name
203 # 2) Name of the model class referenced by this relationship
204 # 3) Column name in *this* table
3b1fa91b 205 __PACKAGE__->belongs_to(role => 'MyApp::Schema::Result::Role', 'role_id');
3533daff 206
905a3a26 207The code for these three sets of updates is obviously very similar to
3b1fa91b 208the edits we made to the C<Book>, C<Author>, and C<BookAuthor>
4b4d3884 209classes created in Chapter 3.
3533daff 210
636ba9f7 211Note that we do not need to make any change to the
212C<lib/MyApp/> schema file. It simply tells DBIC to load all
213of the Result Class and ResultSet Class files it finds in below the
214C<lib/MyApp/Schema> directory, so it will automatically pick up our
acbd7bdd 215new table information.
d442cc9f 216
218=head2 Sanity-Check Reload of Development Server
905a3a26 220We aren't ready to try out the authentication just yet; we only want
221to do a quick check to be sure our model loads correctly. Press
222C<Ctrl-C> to kill the previous server instance (if it's still running)
3533daff 223and restart it:
d442cc9f 224
225 $ script/
227Look for the three new model objects in the startup debug output:
229 ...
230 .-------------------------------------------------------------------+----------.
231 | Class | Type |
232 +-------------------------------------------------------------------+----------+
233 | MyApp::Controller::Books | instance |
234 | MyApp::Controller::Root | instance |
d0496197 235 | MyApp::Model::DB | instance |
236 | MyApp::Model::DB::Author | class |
3b1fa91b 237 | MyApp::Model::DB::Book | class |
238 | MyApp::Model::DB::BookAuthor | class |
239 | MyApp::Model::DB::Role | class |
240 | MyApp::Model::DB::User | class |
241 | MyApp::Model::DB::UserRole | class |
d442cc9f 242 | MyApp::View::TT | instance |
243 '-------------------------------------------------------------------+----------'
244 ...
acbd7bdd 246Again, notice that your "Result Class" classes have been "re-loaded"
3533daff 247by Catalyst under C<MyApp::Model>.
d442cc9f 248
250=head2 Include Authentication and Session Plugins
905a3a26 252Edit C<lib/> and update it as follows (everything below
3533daff 253C<StackTrace> is new):
d442cc9f 254
acbd7bdd 255 # Load plugins
256 use Catalyst qw/-Debug
3b1fa91b 257 ConfigLoader
258 Static::Simple
efdaddec 259
3b1fa91b 260 StackTrace
efdaddec 261
3b1fa91b 262 Authentication
efdaddec 263
3b1fa91b 264 Session
265 Session::Store::FastMmap
266 Session::State::Cookie
267 /;
d442cc9f 268
636ba9f7 269B<Note:> As discussed in MoreCatalystBasics, different versions of
270C<Catalyst::Devel> have used a variety of methods to load the plugins.
533fee73 271You can put the plugins in the C<use Catalyst> statement if you prefer.
94d8da41 272
905a3a26 273The C<Authentication> plugin supports Authentication while the
274C<Session> plugins are required to maintain state across multiple HTTP
6d0971ad 276
905a3a26 277Note that the only required Authentication class is the main one. This
278is a change that occurred in version 0.09999_01 of the
279C<Authentication> plugin. You B<do not need> to specify a particular
280Authentication::Store or Authentication::Credential plugin. Instead,
281indicate the Store and Credential you want to use in your application
6d0971ad 282configuration (see below).
3b1fa91b 284Make sure you include the additional plugins as new dependencies in
285the Makefile.PL file something like this:
287 requires (
288 'Catalyst::Plugin::Authentication' => '0',
289 'Catalyst::Plugin::Session' => '0',
290 'Catalyst::Plugin::Session::Store::FastMmap' => '0',
291 'Catalyst::Plugin::Session::State::Cookie' => '0',
292 );
905a3a26 294Note that there are several options for
297is generally a good choice if you are on Unix; try
298L<Session::Store::File|Catalyst::Plugin::Session::Store::File> if you
299are on Win32) -- consult
300L<Session::Store|Catalyst::Plugin::Session::Store> and its subclasses
3533daff 301for additional information and options (for example to use a database-
302backed session store).
d442cc9f 303
305=head2 Configure Authentication
3b1fa91b 307There are a variety of ways to provide configuration information to
efdaddec 308L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication>.
309Here we will use
311because it automatically sets a reasonable set of defaults for us. Open
312C<lib/> and place the following text above the call to
315 # Configure SimpleDB Authentication
316 __PACKAGE__->config->{'Plugin::Authentication'} = {
317 default => {
318 class => 'SimpleDB',
3b1fa91b 319 user_model => 'DB::User',
efdaddec 320 password_type => 'clear',
321 },
322 };
324We could have placed this configuration in C<myapp.conf>, but placing
325it in C<lib/> is probably a better place since it's not likely
326something that users of your application will want to change during
c3cf3bc3 327deployment (or you could use a mixture: leave C<class> and
328C<user_model> defined in C<lib/> as we show above, but place
329C<password_type> in C<myapp.conf> to allow the type of password to be
330easily modified during deployment). We will stick with putting
331all of the authentication-related configuration in C<lib/>
332for the tutorial, but if you wish to use C<myapp.conf>, just convert
333to the following code:
335 <Plugin::Authentication>
336 use_session 1
337 <default>
338 password_type self_check
3b1fa91b 339 user_model DB::User
c3cf3bc3 340 class SimpleDB
341 </default>
342 </Plugin::Authentication>
344B<TIP:> Here is a short script that will dump the contents of
345C<MyApp->config> to L<Config::General|Config::General> format in
348 $ perl -Ilib -e 'use MyApp; use Config::General;
349 Config::General->new->save_file("myapp.conf", MyApp->config);'
d442cc9f 350
c4fa597d 351B<NOTE:> Because we are using SimpleDB along with a database layout
352that complies with its default assumptions, we don't need to specify
353the names of the columns where our username and password information
354is stored (hence, the "Simple" part of "SimpleDB"). That being said,
87236f03 355SimpleDB lets you specify that type of information if you need to.
c4fa597d 356Take a look at
358for details.
1390ef0e 360
d442cc9f 361=head2 Add Login and Logout Controllers
363Use the Catalyst create script to create two stub controller files:
365 $ script/ controller Login
366 $ script/ controller Logout
636ba9f7 368You could easily use a single controller here. For example, you could
369have a C<User> controller with both C<login> and C<logout> actions.
370Remember, Catalyst is designed to be very flexible, and leaves such
fbbb9084 371matters up to you, the designer and programmer.
d442cc9f 372
636ba9f7 373Then open C<lib/MyApp/Controller/>, locate the
374C<sub index :Path :Args(0)> method (or C<sub index : Private> if you
375are using an older version of Catalyst) that was automatically
376inserted by the helpers when we created the Login controller above,
fbbb9084 377and update the definition of C<sub index> to match:
d442cc9f 378
379 =head2 index
efdaddec 380
d442cc9f 381 Login logic
efdaddec 382
d442cc9f 383 =cut
efdaddec 384
ae492862 385 sub index :Path :Args(0) {
d442cc9f 386 my ($self, $c) = @_;
efdaddec 387
d442cc9f 388 # Get the username and password from form
389 my $username = $c->request->params->{username} || "";
390 my $password = $c->request->params->{password} || "";
efdaddec 391
d442cc9f 392 # If the username and password values were found in form
393 if ($username && $password) {
394 # Attempt to log the user in
905a3a26 395 if ($c->authenticate({ username => $username,
5fefca35 396 password => $password } )) {
d442cc9f 397 # If successful, then let them use the application
0416017e 398 $c->response->redirect($c->uri_for(
399 $c->controller('Books')->action_for('list')));
d442cc9f 400 return;
401 } else {
402 # Set an error message
403 $c->stash->{error_msg} = "Bad username or password.";
404 }
405 }
efdaddec 406
d442cc9f 407 # If either of above don't work out, send to the login page
408 $c->stash->{template} = 'login.tt2';
409 }
3b1fa91b 411Be sure to remove the C<$c-E<gt>response-E<gt>body('Matched MyApp::Controller::Login in Login.');>
412line of the C<sub index>.
d442cc9f 414This controller fetches the C<username> and C<password> values from the
905a3a26 415login form and attempts to authenticate the user. If successful, it
416redirects the user to the book list page. If the login fails, the user
417will stay at the login page and receive an error message. If the
418C<username> and C<password> values are not present in the form, the
f632e28b 419user will be taken to the empty login form.
d442cc9f 420
636ba9f7 421Note that we could have used something like "C<sub default :Path>",
422however, it is generally recommended (partly for historical reasons,
423and partly for code clarity) only to use C<default> in
424C<MyApp::Controller::Root>, and then mainly to generate the 404 not
85d49fb6 425found page for the application.
ae492862 426
fbbb9084 427Instead, we are using "C<sub somename :Path :Args(0) {...}>" here to
905a3a26 428specifically match the URL C</login>. C<Path> actions (aka, "literal
429actions") create URI matches relative to the namespace of the
430controller where they are defined. Although C<Path> supports
431arguments that allow relative and absolute paths to be defined, here
432we use an empty C<Path> definition to match on just the name of the
433controller itself. The method name, C<index>, is arbitrary. We make
ae492862 434the match even more specific with the C<:Args(0)> action modifier --
905a3a26 435this forces the match on I<only> C</login>, not
d442cc9f 436C</login/somethingelse>.
905a3a26 438Next, update the corresponding method in
3533daff 439C<lib/MyApp/Controller/> to match:
d442cc9f 440
441 =head2 index
efdaddec 442
d442cc9f 443 Logout logic
efdaddec 444
d442cc9f 445 =cut
efdaddec 446
ae492862 447 sub index :Path :Args(0) {
d442cc9f 448 my ($self, $c) = @_;
efdaddec 449
d442cc9f 450 # Clear the user's state
451 $c->logout;
efdaddec 452
d442cc9f 453 # Send the user to the starting point
454 $c->response->redirect($c->uri_for('/'));
455 }
905a3a26 457As with the login controller, be sure to delete the
14e5ed66 458C<$c-E<gt>response-E<gt>body('Matched MyApp::Controller::Logout in Logout.');>
d442cc9f 459line of the C<sub index>.
462=head2 Add a Login Form TT Template Page
464Create a login form by opening C<root/src/login.tt2> and inserting:
466 [% META title = 'Login' %]
efdaddec 467
d442cc9f 468 <!-- Login form -->
8a7c5151 469 <form method="post" action="[% c.uri_for('/login') %]">
d442cc9f 470 <table>
471 <tr>
472 <td>Username:</td>
473 <td><input type="text" name="username" size="40" /></td>
474 </tr>
475 <tr>
476 <td>Password:</td>
477 <td><input type="password" name="password" size="40" /></td>
478 </tr>
479 <tr>
480 <td colspan="2"><input type="submit" name="submit" value="Submit" /></td>
481 </tr>
482 </table>
483 </form>
486=head2 Add Valid User Check
488We need something that provides enforcement for the authentication
489mechanism -- a I<global> mechanism that prevents users who have not
490passed authentication from reaching any pages except the login page.
491This is generally done via an C<auto> action/method (prior to Catalyst
492v5.66, this sort of thing would go in C<>, but starting in
493v5.66, the preferred location is C<lib/MyApp/Controller/>).
495Edit the existing C<lib/MyApp/Controller/> class file and insert
496the following method:
498 =head2 auto
efdaddec 499
d442cc9f 500 Check if there is a user and, if not, forward to login page
efdaddec 501
d442cc9f 502 =cut
efdaddec 503
d442cc9f 504 # Note that 'auto' runs after 'begin' but before your actions and that
905a3a26 505 # 'auto's "chain" (all from application path to most specific class are run)
d442cc9f 506 # See the 'Actions' section of 'Catalyst::Manual::Intro' for more info.
507 sub auto : Private {
508 my ($self, $c) = @_;
efdaddec 509
d442cc9f 510 # Allow unauthenticated users to reach the login page. This
191dee29 511 # allows unauthenticated users to reach any action in the Login
d442cc9f 512 # controller. To lock it down to a single action, we could use:
513 # if ($c->action eq $c->controller('Login')->action_for('index'))
905a3a26 514 # to only allow unauthenticated access to the 'index' action we
d442cc9f 515 # added above.
516 if ($c->controller eq $c->controller('Login')) {
517 return 1;
518 }
efdaddec 519
d442cc9f 520 # If a user doesn't exist, force login
521 if (!$c->user_exists) {
522 # Dump a log message to the development server debug output
523 $c->log->debug('***Root::auto User not found, forwarding to /login');
524 # Redirect the user to the login page
525 $c->response->redirect($c->uri_for('/login'));
526 # Return 0 to cancel 'post-auto' processing and prevent use of application
527 return 0;
528 }
efdaddec 529
d442cc9f 530 # User found, so return 1 to continue with processing after this 'auto'
531 return 1;
532 }
636ba9f7 534As discussed in
535L<Catalyst::Manual::Tutorial::MoreCatalystBasics/CREATE A CATALYST CONTROLLER>,
536every C<auto> method from the application/root controller down to the
537most specific controller will be called. By placing the
538authentication enforcement code inside the C<auto> method of
539C<lib/MyApp/Controller/> (or C<lib/>), it will be
540called for I<every> request that is received by the entire
0416017e 541application.
d442cc9f 542
544=head2 Displaying Content Only to Authenticated Users
546Let's say you want to provide some information on the login page that
547changes depending on whether the user has authenticated yet. To do
548this, open C<root/src/login.tt2> in your editor and add the following
549lines to the bottom of the file:
acbd7bdd 551 ...
d442cc9f 552 <p>
553 [%
905a3a26 554 # This code illustrates how certain parts of the TT
d442cc9f 555 # template will only be shown to users who have logged in
556 %]
8a7c5151 557 [% IF c.user_exists %]
558 Please Note: You are already logged in as '[% c.user.username %]'.
559 You can <a href="[% c.uri_for('/logout') %]">logout</a> here.
d442cc9f 560 [% ELSE %]
561 You need to log in to use this application.
562 [% END %]
563 [%#
564 Note that this whole block is a comment because the "#" appears
905a3a26 565 immediate after the "[%" (with no spaces in between). Although it
566 can be a handy way to temporarily "comment out" a whole block of
567 TT code, it's probably a little too subtle for use in "normal"
d442cc9f 568 comments.
569 %]
3533daff 570 </p>
d442cc9f 571
572Although most of the code is comments, the middle few lines provide a
573"you are already logged in" reminder if the user returns to the login
574page after they have already authenticated. For users who have not yet
575authenticated, a "You need to log in..." message is displayed (note the
576use of an IF-THEN-ELSE construct in TT).
579=head2 Try Out Authentication
581Press C<Ctrl-C> to kill the previous server instance (if it's still
582running) and restart it:
584 $ script/
636ba9f7 586B<IMPORTANT NOTE:> If you are having issues with authentication on
587Internet Explorer, be sure to check the system clocks on both your
588server and client machines. Internet Explorer is very picky about
acbd7bdd 589timestamps for cookies. You can quickly sync a Debian system by
590installing the "ntpdate" package:
592 sudo aptitude -y install ntpdate
594And then run the following command:
25ed8f40 595
acbd7bdd 596 sudo ntpdate-debian
d442cc9f 597
acbd7bdd 598Or, depending on your firewall configuration:
600 sudo ntpdate-debian -u
636ba9f7 602Note: NTP can be a little more finicky about firewalls because it uses
acbd7bdd 603UDP vs. the more common TCP that you see with most Internet protocols.
604Worse case, you might have to manually set the time on your development
605box instead of using NTP.
1390ef0e 606
636ba9f7 607Now trying going to L<http://localhost:3000/books/list> and you should
608be redirected to the login page, hitting Shift+Reload or Ctrl+Reload
609if necessary (the "You are already logged in" message should I<not>
610appear -- if it does, click the C<logout> button and try again). Note
611the C<***Root::auto User not found...> debug message in the
612development server output. Enter username C<test01> and password
1390ef0e 613C<mypass>, and you should be taken to the Book List page.
d442cc9f 614
615Open C<root/src/books/list.tt2> and add the following lines to the
3533daff 616bottom (below the closing </table> tag):
d442cc9f 617
618 <p>
8a7c5151 619 <a href="[% c.uri_for('/login') %]">Login</a>
0416017e 620 <a href="[% c.uri_for(c.controller.action_for('form_create')) %]">Create</a>
d442cc9f 621 </p>
905a3a26 623Reload your browser and you should now see a "Login" and "Create" links
624at the bottom of the page (as mentioned earlier, you can update template
625files without reloading the development server). Click the first link
626to return to the login page. This time you I<should> see the "You are
d442cc9f 627already logged in" message.
629Finally, click the C<You can logout here> link on the C</login> page.
630You should stay at the login page, but the message should change to "You
631need to log in to use this application."
efdaddec 636In this section we increase the security of our system by converting
637from cleartext passwords to SHA-1 password hashes that include a
638random "salt" value to make them extremely difficult to crack with
639dictionary and "rainbow table" attacks.
d442cc9f 640
641B<Note:> This section is optional. You can skip it and the rest of the
642tutorial will function normally.
fbbb9084 644Be aware that even with the techniques shown in this section, the browser
d442cc9f 645still transmits the passwords in cleartext to your application. We are
646just avoiding the I<storage> of cleartext passwords in the database by
efdaddec 647using a salted SHA-1 hash. If you are concerned about cleartext passwords
d442cc9f 648between the browser and your application, consider using SSL/TLS, made
efdaddec 649easy with the Catalyst plugin Catalyst::Plugin:RequireSSL.
d442cc9f 650
efdaddec 652=head2 Install DBIx::Class::EncodedColumn
d442cc9f 653
efdaddec 654L<DBIx::Class::EncodedColumn|DBIx::Class::EncodedColumn> provides features
655that can greatly simplify the maintenance of passwords. It's currently
656not available as a .deb package in the normal Debian repositories, so let's
657install it directly from CPAN:
d442cc9f 658
efdaddec 659 $ sudo cpan DBIx::Class::EncodedColumn
d0496197 660
d442cc9f 661
efdaddec 662=head2 Re-Run the DBIC::Schema Model Helper to Include DBIx::Class::EncodedColumn
d442cc9f 663
efdaddec 664Next, we can re-run the model helper to have it include
665L<DBIx::Class::EncodedColumn|DBIx::Class::EncodedColumn> in all of the
666Result Classes it generates for us. Simply use the same command we
667saw in Chapters 3 and 4, but add C<,EncodedColumn> to the C<components>
d442cc9f 669
efdaddec 670 $ script/ model DB DBIC::Schema MyApp::Schema \
671 create=static components=TimeStamp,EncodedColumn dbi:SQLite:myapp.db
d442cc9f 672
efdaddec 673If you then open one of the Result Classes, you will see that it
674includes EncodedColumn in the C<load_components> line. Take a look at
3b1fa91b 675C<lib/MyApp/Schema/Result/> since that's the main class where we
efdaddec 676want to use hashed and salted passwords:
678 __PACKAGE__->load_components("InflateColumn::DateTime", "TimeStamp", "EncodedColumn", "Core");
681=head2 Modify the "password" Column to Use EncodedColumn
3b1fa91b 683Open the file C<lib/MyApp/Schema/Result/> and enter the following
efdaddec 684text below the "# DO NOT MODIFY THIS OR ANYTHING ABOVE!" line but above
685the closing "1;":
687 # Have the 'password' column use a SHA-1 hash and 10-character salt
688 # with hex encoding; Generate the 'check_password" method
689 __PACKAGE__->add_columns(
690 'password' => {
691 data_type => "TEXT",
692 size => undef,
693 encode_column => 1,
694 encode_class => 'Digest',
695 encode_args => {salt_length => 10},
696 encode_check_method => 'check_password',
697 },
698 );
700This redefines the automatically generated definition for the password
701fields at the top of the Result Class file to now use EncodedColumn
702logic (C<encoded_column> is set to 1). C<encode_class> can be set to
703either C<Digest> to use
705or C<Crypt::Eksblowfish::Bcrypt> for
707C<encode_args> is then used to customize the type of Digest you
708selected. Here we only specified the size of the salt to use, but
709we could have also modified the hashing algorithm ('SHA-256' is
710the default) and the format to use ('base64' is the default, but
711'hex' and 'binary' are other options). To use these, you could
712change the C<encode_args> to something like:
714 encode_args => {algorithm => 'SHA-1',
715 format => 'hex',
716 salt_length => 10},
719=head2 Load Hashed Passwords in the Database
721Next, let's create a quick script to load some hashed and salted passwords
722into the C<password> column of our C<users> table. Open the file
723C<> in your editor and enter the following text:
725 #!/usr/bin/perl
727 use strict;
728 use warnings;
730 use MyApp::Schema;
732 my $schema = MyApp::Schema->connect('dbi:SQLite:myapp.db');
3b1fa91b 734 my @users = $schema->resultset('User')->all;
efdaddec 735
736 foreach my $user (@users) {
737 $user->password('mypass');
738 $user->update;
739 }
741EncodedColumn lets us simple call C<$user->check_password($password)>
742to see if the user has supplied the correct password, or, as we show
743above, call C<$user->update($new_password)> to update the hashed
744password stored for this user.
746Then run the following command:
748 $ perl -Ilib
750We had to use the C<-Ilib> arguement to tell perl to look under the
751C<lib> directory for our C<MyApp::Schema> model.
753Then dump the users table to verify that it worked:
3b1fa91b 755 $ sqlite3 myapp.db "select * from user"
efdaddec 756 1|test01|38d3974fa9e9263099f7bc2574284b2f55473a9bM=fwpX2NR8||Joe|Blow|1
757 2|test02|6ed8586587e53e0d7509b1cfed5df08feadc68cbMJlnPyPt0I||Jane|Doe|1
758 3|test03|af929a151340c6aed4d54d7e2651795d1ad2e2f7UW8dHoGv9z||No|Go|0
760As you can see, the passwords are much harder to steal from the
761database. Also note that this demonstrates how to use a DBIx::Class
762model outside of your web application -- a very useful feature in many
766=head2 Enable Hashed and Salted Passwords
768Edit C<lib/> and update it to match the following text (the only change
769is to the C<password_type> field):
771 # Configure SimpleDB Authentication
772 __PACKAGE__->config->{'Plugin::Authentication'} = {
773 default => {
774 class => 'SimpleDB',
3b1fa91b 775 user_model => 'DB::User',
efdaddec 776 password_type => 'self_check',
777 },
778 };
780The use of C<self_check> will cause
781Catalyst::Plugin::Authentication::Store::DBIC to call the
782C<check_password> method we enabled on our C<password> columns.
d442cc9f 783
1390ef0e 784
d442cc9f 785=head2 Try Out the Hashed Passwords
787Press C<Ctrl-C> to kill the previous server instance (if it's still
788running) and restart it:
790 $ script/
792You should now be able to go to L<http://localhost:3000/books/list> and
fbbb9084 793login as before. When done, click the "logout" link on the login page
d442cc9f 794(or point your browser at L<http://localhost:3000/logout>).
d442cc9f 796
4b4d3884 799As discussed in the previous chapter of the tutorial, C<flash> allows
800you to set variables in a way that is very similar to C<stash>, but it
801will remain set across multiple requests. Once the value is read, it
802is cleared (unless reset). Although C<flash> has nothing to do with
803authentication, it does leverage the same session plugins. Now that
804those plugins are enabled, let's go back and update the "delete and
805redirect with query parameters" code seen at the end of the L<Basic
806CRUD|Catalyst::Manual::Tutorial::BasicCRUD> chapter of the tutorial to
807take advantage of C<flash>.
d442cc9f 808
809First, open C<lib/MyApp/Controller/> and modify C<sub delete>
3533daff 810to match the following (everything after the model search line of code
811has changed):
d442cc9f 812
905a3a26 813 =head2 delete
efdaddec 814
d442cc9f 815 Delete a book
efdaddec 816
d442cc9f 817 =cut
efdaddec 818
fbbb9084 819 sub delete :Chained('object') :PathPart('delete') :Args(0) {
820 my ($self, $c) = @_;
efdaddec 821
fbbb9084 822 # Use the book object saved by 'object' and delete it along
823 # with related 'book_authors' entries
824 $c->stash->{object}->delete;
efdaddec 825
d442cc9f 826 # Use 'flash' to save information across requests until it's read
827 $c->flash->{status_msg} = "Book deleted";
efdaddec 828
3533daff 829 # Redirect the user back to the list page
0416017e 830 $c->response->redirect($c->uri_for($self->action_for('list')));
d442cc9f 831 }
1390ef0e 833Next, open C<root/src/wrapper.tt2> and update the TT code to pull from
d442cc9f 834flash vs. the C<status_msg> query parameter:
1390ef0e 836 ...
d442cc9f 837 <div id="content">
1390ef0e 838 [%# Status and error messages %]
839 <span class="message">[% status_msg || c.flash.status_msg %]</span>
840 <span class="error">[% error_msg %]</span>
841 [%# This is where TT will stick all of your template's contents. -%]
842 [% content %]
843 </div><!-- end content -->
844 ...
905a3a26 845
636ba9f7 846Although the sample above only shows the C<content> div, leave the
1390ef0e 847rest of the file intact -- the only change we made to the C<wrapper.tt2>
636ba9f7 848was to add "C<|| c.request.params.status_msg>" to the
1390ef0e 849C<E<lt>span class="message"E<gt>> line.
d442cc9f 850
852=head2 Try Out Flash
636ba9f7 854Restart the development server, log in, and then point your browser to
855L<http://localhost:3000/books/url_create/Test/1/4> to create an extra
856several books. Click the "Return to list" link and delete one of the
857"Test" books you just added. The C<flash> mechanism should retain our
3533daff 858"Book deleted" status message across the redirect.
d442cc9f 859
860B<NOTE:> While C<flash> will save information across multiple requests,
861I<it does get cleared the first time it is read>. In general, this is
862exactly what you want -- the C<flash> message will get displayed on
863the next screen where it's appropriate, but it won't "keep showing up"
864after that first time (unless you reset it). Please refer to
865L<Catalyst::Plugin::Session|Catalyst::Plugin::Session> for additional
1390ef0e 868
3533daff 869=head2 Switch To Flash-To-Stash
636ba9f7 871Although the a use of flash above works well, the
1390ef0e 872C<status_msg || c.flash.status_msg> statement is a little ugly. A nice
905a3a26 873alternative is to use the C<flash_to_stash> feature that automatically
1390ef0e 874copies the content of flash to stash. This makes your controller
905a3a26 875and template code work regardless of where it was directly access, a
fbbb9084 876forward, or a redirect. To enable C<flash_to_stash>, you can either
905a3a26 877set the value in C<lib/> by changing the default
3533daff 878C<__PACKAGE__-E<gt>config> setting to something like:
880 __PACKAGE__->config(
efdaddec 881 name => 'MyApp',
3533daff 882 session => {flash_to_stash => 1}
883 );
45d511e0 885B<or> add the following to C<myapp.conf>:
3533daff 886
45d511e0 887 <session>
888 flash_to_stash 1
889 </session>
3533daff 890
905a3a26 891The C<__PACKAGE__-E<gt>config> option is probably preferable here
892since it's not something you will want to change at runtime without it
3533daff 893possibly breaking some of your code.
1390ef0e 895Then edit C<root/src/wrapper.tt2> and change the C<status_msg> line
896to match the following:
3533daff 897
898 <span class="message">[% status_msg %]</span>
900Restart the development server and go to
905a3a26 901L<http://localhost:3000/books/list> in your browser. Delete another
3533daff 902of the "Test" books you added in the previous step. Flash should still
903maintain the status message across the redirect even though you are no
8a7c5151 904longer explicitly accessing C<c.flash>.
3533daff 905
d442cc9f 906
907=head1 AUTHOR
909Kennedy Clark, C<>
911Please report any errors, issues or suggestions to the author. The
912most recent version of the Catalyst Tutorial can be found at
82ab4bbf 913L<>.
d442cc9f 914
45c7830f 915Copyright 2006-2008, Kennedy Clark, under Creative Commons License
95674086 916(L<>).