rollback to use Catalyst qw/@plugins/
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial / Authorization.pod
d442cc9f 1=head1 NAME
3533daff 3Catalyst::Manual::Tutorial::Authorization - Catalyst Tutorial - Part 6: Authorization
d442cc9f 4
6=head1 OVERVIEW
3533daff 8This is B<Part 6 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 32L<Authentication|Catalyst::Manual::Tutorial::Authentication>
d442cc9f 33
34=item 6
3533daff 36B<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>
50=item 10
d442cc9f 52L<Appendices|Catalyst::Manual::Tutorial::Appendices>
d442cc9f 57=head1 DESCRIPTION
59This part of the tutorial adds role-based authorization to the existing
9ad715b3 60authentication implemented in Part 5. It provides simple examples of
d442cc9f 61how to use roles in both TT templates and controller actions. The first
62half looks at manually configured authorization. The second half looks
63at how the ACL authorization plugin can simplify your code.
65You can checkout the source code for this example from the catalyst
66subversion repository as per the instructions in
71In this section you learn how to manually configure authorization.
73=head2 Update Plugins to Include Support for Authorization
75Edit C<lib/> and add C<Authorization::Roles> to the list:
b411df01 77 use Catalyst qw/
d442cc9f 78 -Debug
79 ConfigLoader
80 Static::Simple
905a3a26 81
d442cc9f 82 StackTrace
905a3a26 83
d442cc9f 84 Authentication
d442cc9f 85 Authorization::Roles
905a3a26 86
d442cc9f 87 Session
88 Session::Store::FastMmap
89 Session::State::Cookie
b411df01 90 /;
d442cc9f 91
93=head2 Add Config Information for Authorization
905a3a26 95Edit C<myapp.conf> and update it to match the following (the
3533daff 96C<role_relation> and C<role_field> definitions are new):
d442cc9f 97
c010ae0d 98 name MyApp
99 <authentication>
100 default_realm dbic
101 <realms>
102 <dbic>
103 <credential>
3533daff 104 # Note this first definition would be the same as setting
105 # __PACKAGE__->config->{authentication}->{realms}->{dbic}
905a3a26 106 # ->{credential} = 'Password' in lib/
3533daff 107 #
108 # Specify that we are going to do password-based auth
c010ae0d 109 class Password
3533daff 110 # This is the name of the field in the users table with the
111 # password stored in it
c010ae0d 112 password_field password
d0496197 113 # Switch to more secure hashed passwords
114 password_type hashed
115 # Use the SHA-1 hashing algorithm
116 password_hash_type SHA-1
117 </credential>
c010ae0d 118 <store>
3533daff 119 # Use DBIC to retrieve username, password & role information
c010ae0d 120 class DBIx::Class
905a3a26 121 # This is the model object created by Catalyst::Model::DBIC
d0496197 122 # from your schema (you created 'MyApp::Schema::User' but as
905a3a26 123 # the Catalyst startup debug messages show, it was loaded as
d0496197 124 # 'MyApp::Model::DB::Users').
905a3a26 125 # NOTE: Omit 'MyApp::Model' here just as you would when using
d0496197 126 # '$c->model("DB::Users)'
127 user_class DB::Users
905a3a26 128 # This is the name of the field in your 'users' table that
3533daff 129 # contains the user's name
c010ae0d 130 id_field username
3533daff 131 # This is the name of a many_to_many relation in the users
132 # object that points to the roles for that user
c010ae0d 133 role_relation roles
3533daff 134 # This is the name of field in the roles table that contains
135 # the role information
c010ae0d 136 role_field role
d0496197 137 </store>
138 </dbic>
139 </realms>
140 </authentication>
d442cc9f 141
143=head2 Add Role-Specific Logic to the "Book List" Template
145Open C<root/src/books/list.tt2> in your editor and add the following
146lines to the bottom of the file:
8a7c5151 148 <p>Hello [% c.user.username %], you have the following roles:</p>
905a3a26 149
d442cc9f 150 <ul>
151 [% # Dump list of roles -%]
8a7c5151 152 [% FOR role = c.user.roles %]<li>[% role %]</li>[% END %]
d442cc9f 153 </ul>
905a3a26 154
d442cc9f 155 <p>
156 [% # Add some simple role-specific logic to template %]
157 [% # Use $c->check_user_roles() to check authz -%]
8a7c5151 158 [% IF c.check_user_roles('user') %]
d442cc9f 159 [% # Give normal users a link for 'logout' %]
8a7c5151 160 <a href="[% c.uri_for('/logout') %]">Logout</a>
d442cc9f 161 [% END %]
905a3a26 162
d442cc9f 163 [% # Can also use $c->user->check_roles() to check authz -%]
8a7c5151 164 [% IF c.check_user_roles('admin') %]
d442cc9f 165 [% # Give admin users a link for 'create' %]
8a7c5151 166 <a href="[% c.uri_for('form_create') %]">Create</a>
d442cc9f 167 [% END %]
168 </p>
170This code displays a different combination of links depending on the
171roles assigned to the user.
173=head2 Limit C<Books::add> to C<admin> Users
175C<IF> statements in TT templates simply control the output that is sent
176to the user's browser; it provides no real enforcement (if users know or
177guess the appropriate URLs, they are still perfectly free to hit any
178action within your application). We need to enhance the controller
179logic to wrap restricted actions with role-validation logic.
181For example, we might want to restrict the "formless create" action to
182admin-level users by editing C<lib/MyApp/Controller/> and
183updating C<url_create> to match the following code:
185 =head2 url_create
187 Create a book with the supplied title and rating,
188 with manual authorization
905a3a26 189
d442cc9f 190 =cut
905a3a26 191
d442cc9f 192 sub url_create : Local {
193 # In addition to self & context, get the title, rating & author_id args
194 # from the URL. Note that Catalyst automatically puts extra information
195 # after the "/<controller_name>/<action_name/" into @_
196 my ($self, $c, $title, $rating, $author_id) = @_;
905a3a26 197
d442cc9f 198 # Check the user's roles
199 if ($c->check_user_roles('admin')) {
905a3a26 200 # Call create() on the book model object. Pass the table
d442cc9f 201 # columns/field values we want to set as hash values
d0496197 202 my $book = $c->model('DB::Books')->create({
d442cc9f 203 title => $title,
204 rating => $rating
205 });
905a3a26 206
207 # Add a record to the join table for this book, mapping to
d442cc9f 208 # appropriate author
209 $book->add_to_book_authors({author_id => $author_id});
210 # Note: Above is a shortcut for this:
211 # $book->create_related('book_authors', {author_id => $author_id});
905a3a26 212
d442cc9f 213 # Assign the Book object to the stash for display in the view
214 $c->stash->{book} = $book;
905a3a26 215
d442cc9f 216 # This is a hack to disable XSUB processing in Data::Dumper
217 # (it's used in the view). This is a work-around for a bug in
218 # the interaction of some versions or Perl, Data::Dumper & DBIC.
219 # You won't need this if you aren't using Data::Dumper (or if
905a3a26 220 # you are running DBIC 0.06001 or greater), but adding it doesn't
d442cc9f 221 # hurt anything either.
222 $Data::Dumper::Useperl = 1;
905a3a26 223
d442cc9f 224 # Set the TT template to use
225 $c->stash->{template} = 'books/create_done.tt2';
226 } else {
227 # Provide very simple feedback to the user
228 $c->response->body('Unauthorized!');
229 }
230 }
233To add authorization, we simply wrap the main code of this method in an
234C<if> statement that calls C<check_user_roles>. If the user does not
235have the appropriate permissions, they receive an "Unauthorized!"
236message. Note that we intentionally chose to display the message this
237way to demonstrate that TT templates will not be used if the response
238body has already been set. In reality you would probably want to use a
239technique that maintains the visual continuity of your template layout
240(for example, using the "status" or "error" message feature added in
9ad715b3 241Part 3).
d442cc9f 242
243B<TIP>: If you want to keep your existing C<url_create> method, you can
244create a new copy and comment out the original by making it look like a
245Pod comment. For example, put something like C<=begin> before C<sub add
246: Local {> and C<=end> after the closing C<}>.
248=head2 Try Out Authentication And Authorization
250Press C<Ctrl-C> to kill the previous server instance (if it's still
251running) and restart it:
253 $ script/
255Now trying going to L<http://localhost:3000/books/list> and you should
256be taken to the login page (you might have to C<Shift+Reload> your
905a3a26 257browser and/or click the "Logout" link on the book list page). Try
258logging in with both C<test01> and C<test02> (both use a password
259of C<mypass>) and notice how the roles information updates at the
d442cc9f 260bottom of the "Book List" page. Also try the C<Logout> link on the
261book list page.
263Now the "url_create" URL will work if you are already logged in as user
264C<test01>, but receive an authorization failure if you are logged in as
265C<test02>. Try:
267 http://localhost:3000/books/url_create/test/1/6
269while logged in as each user. Use one of the 'Logout' links (or go to
905a3a26 270L<http://localhost:3000/logout> in your browser directly) when you are
d442cc9f 271done.
276This section takes a brief look at how the
905a3a26 278plugin can automate much of the work required to perform role-based
d442cc9f 279authorization in a Catalyst application.
281=head2 Add the C<Catalyst::Plugin::Authorization::ACL> Plugin
283Open C<lib/> in your editor and add the following plugin to the
284C<use Catalyst> statement:
286 Authorization::ACL
288Note that the remaining C<use Catalyst> plugins from earlier sections
289are not shown here, but they should still be included.
291=head2 Add ACL Rules to the Application Class
293Open C<lib/> in your editor and add the following B<BELOW> the
294C<__PACKAGE__-E<gt>setup;> statement:
296 # Authorization::ACL Rules
297 __PACKAGE__->deny_access_unless(
298 "/books/form_create",
299 [qw/admin/],
300 );
301 __PACKAGE__->deny_access_unless(
302 "/books/form_create_do",
303 [qw/admin/],
304 );
305 __PACKAGE__->deny_access_unless(
306 "/books/delete",
307 [qw/user admin/],
308 );
310Each of the three statements above comprises an ACL plugin "rule". The
311first two rules only allow admin-level users to create new books using
312the form (both the form itself and the data submission logic are
313protected). The third statement allows both users and admins to delete
314books. The C</books/url_create> action will continue to be protected by
315the "manually configured" authorization created earlier in this part of
316the tutorial.
318The ACL plugin permits you to apply allow/deny logic in a variety of
319ways. The following provides a basic overview of the capabilities:
321=over 4
905a3a26 323=item *
d442cc9f 324
325The ACL plugin only operates on the Catalyst "private namespace". You
326are using the private namespace when you use C<Local> actions. C<Path>,
327C<Regex>, and C<Global> allow you to specify actions where the path and
328the namespace differ -- the ACL plugin will not work in these cases.
905a3a26 330=item *
d442cc9f 331
332Each rule is expressed in a separate
333C<__PACKAGE__-E<gt>deny_access_unless()> or
334C<__PACKAGE__-E<gt>allow_access_if()> line (there are several other
335methods that can be used for more complex policies, see the C<METHODS>
336portion of the
338documentation for more details).
905a3a26 340=item *
d442cc9f 341
342Each rule can contain multiple roles but only a single path.
905a3a26 344=item *
d442cc9f 345
346The rules are tried in order (with the "most specific" rules tested
347first), and processing stops at the first "match" where an allow or deny
348is specified. Rules "fall through" if there is not a "match" (where a
349"match" means the user has the specified role). If a "match" is found,
350then processing stops there and the appropriate allow/deny action is
905a3a26 353=item *
d442cc9f 354
355If none of the rules match, then access is allowed.
905a3a26 357=item *
d442cc9f 358
905a3a26 359The rules currently need to be specified in the application class
d442cc9f 360C<lib\> B<after> the C<__PACKAGE__-E<gt>setup;> line.
364=head2 Add a Method to Handle Access Violations
366By default,
368throws an exception when authorization fails. This will take the user
369to the Catalyst debug screen, or a "Please come back later" message if
370you are not using the C<-Debug> flag. This step uses the
371C<access_denied> method in order to provide more appropriate feedback to
372the user.
374Open C<lib/MyApp/Controller/> in your editor and add the
375following method:
377 =head2 access_denied
905a3a26 378
d442cc9f 379 Handle Catalyst::Plugin::Authorization::ACL access denied exceptions
905a3a26 380
d442cc9f 381 =cut
905a3a26 382
d442cc9f 383 sub access_denied : Private {
384 my ($self, $c) = @_;
905a3a26 385
d442cc9f 386 # Set the error message
387 $c->stash->{error_msg} = 'Unauthorized!';
905a3a26 388
d442cc9f 389 # Display the list
390 $c->forward('list');
391 }
905a3a26 393Then run the Catalyst development server script:
d442cc9f 394
395 $ script/
3778bcbe 397Log in as C<test02>. Once at the book list, click the "Create" link
398to try the C<form_create> action. You should receive a red
399"Unauthorized!" error message at the top of the list. (Note that in
400the example code the "Create" link code in C<root/src/books/list.tt2>
401is inside an C<IF> statement that only displays the list to
402admin-level users.) If you log in as C<test01> you should be able to
403view the C<form_create> form and add a new book.
d442cc9f 404
405When you are done, use one of the 'Logout' links (or go to the
406L<http://localhost:3000/logout> URL directly) when you are done.
409=head1 AUTHOR
411Kennedy Clark, C<>
413Please report any errors, issues or suggestions to the author. The
414most recent version of the Catalyst Tutorial can be found at
d712b826 415L<>.
d442cc9f 416
45c7830f 417Copyright 2006-2008, Kennedy Clark, under Creative Commons License
d442cc9f 418(L<>).