Fixing the typos introduced during the last typo fix ;-)
[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
3533daff 128 # This is the name of a many_to_many relation in the users
129 # object that points to the roles for that user
c010ae0d 130 role_relation roles
3533daff 131 # This is the name of field in the roles table that contains
132 # the role information
c010ae0d 133 role_field role
d0496197 134 </store>
135 </dbic>
136 </realms>
137 </authentication>
d442cc9f 138
140=head2 Add Role-Specific Logic to the "Book List" Template
142Open C<root/src/books/list.tt2> in your editor and add the following
143lines to the bottom of the file:
8a7c5151 145 <p>Hello [% c.user.username %], you have the following roles:</p>
905a3a26 146
d442cc9f 147 <ul>
148 [% # Dump list of roles -%]
8a7c5151 149 [% FOR role = c.user.roles %]<li>[% role %]</li>[% END %]
d442cc9f 150 </ul>
905a3a26 151
d442cc9f 152 <p>
153 [% # Add some simple role-specific logic to template %]
154 [% # Use $c->check_user_roles() to check authz -%]
8a7c5151 155 [% IF c.check_user_roles('user') %]
d442cc9f 156 [% # Give normal users a link for 'logout' %]
8a7c5151 157 <a href="[% c.uri_for('/logout') %]">Logout</a>
d442cc9f 158 [% END %]
905a3a26 159
d442cc9f 160 [% # Can also use $c->user->check_roles() to check authz -%]
8a7c5151 161 [% IF c.check_user_roles('admin') %]
d442cc9f 162 [% # Give admin users a link for 'create' %]
8a7c5151 163 <a href="[% c.uri_for('form_create') %]">Create</a>
d442cc9f 164 [% END %]
165 </p>
167This code displays a different combination of links depending on the
168roles assigned to the user.
170=head2 Limit C<Books::add> to C<admin> Users
172C<IF> statements in TT templates simply control the output that is sent
173to the user's browser; it provides no real enforcement (if users know or
174guess the appropriate URLs, they are still perfectly free to hit any
175action within your application). We need to enhance the controller
176logic to wrap restricted actions with role-validation logic.
178For example, we might want to restrict the "formless create" action to
179admin-level users by editing C<lib/MyApp/Controller/> and
180updating C<url_create> to match the following code:
182 =head2 url_create
184 Create a book with the supplied title and rating,
185 with manual authorization
905a3a26 186
d442cc9f 187 =cut
905a3a26 188
d442cc9f 189 sub url_create : Local {
190 # In addition to self & context, get the title, rating & author_id args
191 # from the URL. Note that Catalyst automatically puts extra information
192 # after the "/<controller_name>/<action_name/" into @_
193 my ($self, $c, $title, $rating, $author_id) = @_;
905a3a26 194
d442cc9f 195 # Check the user's roles
196 if ($c->check_user_roles('admin')) {
905a3a26 197 # Call create() on the book model object. Pass the table
d442cc9f 198 # columns/field values we want to set as hash values
d0496197 199 my $book = $c->model('DB::Books')->create({
d442cc9f 200 title => $title,
201 rating => $rating
202 });
905a3a26 203
204 # Add a record to the join table for this book, mapping to
d442cc9f 205 # appropriate author
206 $book->add_to_book_authors({author_id => $author_id});
207 # Note: Above is a shortcut for this:
208 # $book->create_related('book_authors', {author_id => $author_id});
905a3a26 209
d442cc9f 210 # Assign the Book object to the stash for display in the view
211 $c->stash->{book} = $book;
905a3a26 212
d442cc9f 213 # This is a hack to disable XSUB processing in Data::Dumper
214 # (it's used in the view). This is a work-around for a bug in
215 # the interaction of some versions or Perl, Data::Dumper & DBIC.
216 # You won't need this if you aren't using Data::Dumper (or if
905a3a26 217 # you are running DBIC 0.06001 or greater), but adding it doesn't
d442cc9f 218 # hurt anything either.
219 $Data::Dumper::Useperl = 1;
905a3a26 220
d442cc9f 221 # Set the TT template to use
222 $c->stash->{template} = 'books/create_done.tt2';
223 } else {
224 # Provide very simple feedback to the user
225 $c->response->body('Unauthorized!');
226 }
227 }
230To add authorization, we simply wrap the main code of this method in an
231C<if> statement that calls C<check_user_roles>. If the user does not
232have the appropriate permissions, they receive an "Unauthorized!"
233message. Note that we intentionally chose to display the message this
234way to demonstrate that TT templates will not be used if the response
235body has already been set. In reality you would probably want to use a
236technique that maintains the visual continuity of your template layout
237(for example, using the "status" or "error" message feature added in
9ad715b3 238Part 3).
d442cc9f 239
240B<TIP>: If you want to keep your existing C<url_create> method, you can
241create a new copy and comment out the original by making it look like a
242Pod comment. For example, put something like C<=begin> before C<sub add
243: Local {> and C<=end> after the closing C<}>.
245=head2 Try Out Authentication And Authorization
247Press C<Ctrl-C> to kill the previous server instance (if it's still
248running) and restart it:
250 $ script/
252Now trying going to L<http://localhost:3000/books/list> and you should
253be taken to the login page (you might have to C<Shift+Reload> your
905a3a26 254browser and/or click the "Logout" link on the book list page). Try
255logging in with both C<test01> and C<test02> (both use a password
256of C<mypass>) and notice how the roles information updates at the
d442cc9f 257bottom of the "Book List" page. Also try the C<Logout> link on the
258book list page.
260Now the "url_create" URL will work if you are already logged in as user
261C<test01>, but receive an authorization failure if you are logged in as
262C<test02>. Try:
264 http://localhost:3000/books/url_create/test/1/6
266while logged in as each user. Use one of the 'Logout' links (or go to
905a3a26 267L<http://localhost:3000/logout> in your browser directly) when you are
d442cc9f 268done.
273This section takes a brief look at how the
905a3a26 275plugin can automate much of the work required to perform role-based
d442cc9f 276authorization in a Catalyst application.
278=head2 Add the C<Catalyst::Plugin::Authorization::ACL> Plugin
280Open C<lib/> in your editor and add the following plugin to the
281C<use Catalyst> statement:
283 Authorization::ACL
285Note that the remaining C<use Catalyst> plugins from earlier sections
286are not shown here, but they should still be included.
288=head2 Add ACL Rules to the Application Class
290Open C<lib/> in your editor and add the following B<BELOW> the
291C<__PACKAGE__-E<gt>setup;> statement:
293 # Authorization::ACL Rules
294 __PACKAGE__->deny_access_unless(
295 "/books/form_create",
296 [qw/admin/],
297 );
298 __PACKAGE__->deny_access_unless(
299 "/books/form_create_do",
300 [qw/admin/],
301 );
302 __PACKAGE__->deny_access_unless(
303 "/books/delete",
304 [qw/user admin/],
305 );
307Each of the three statements above comprises an ACL plugin "rule". The
308first two rules only allow admin-level users to create new books using
309the form (both the form itself and the data submission logic are
310protected). The third statement allows both users and admins to delete
311books. The C</books/url_create> action will continue to be protected by
312the "manually configured" authorization created earlier in this part of
313the tutorial.
315The ACL plugin permits you to apply allow/deny logic in a variety of
316ways. The following provides a basic overview of the capabilities:
318=over 4
905a3a26 320=item *
d442cc9f 321
322The ACL plugin only operates on the Catalyst "private namespace". You
323are using the private namespace when you use C<Local> actions. C<Path>,
324C<Regex>, and C<Global> allow you to specify actions where the path and
325the namespace differ -- the ACL plugin will not work in these cases.
905a3a26 327=item *
d442cc9f 328
329Each rule is expressed in a separate
330C<__PACKAGE__-E<gt>deny_access_unless()> or
331C<__PACKAGE__-E<gt>allow_access_if()> line (there are several other
332methods that can be used for more complex policies, see the C<METHODS>
333portion of the
335documentation for more details).
905a3a26 337=item *
d442cc9f 338
339Each rule can contain multiple roles but only a single path.
905a3a26 341=item *
d442cc9f 342
343The rules are tried in order (with the "most specific" rules tested
344first), and processing stops at the first "match" where an allow or deny
345is specified. Rules "fall through" if there is not a "match" (where a
346"match" means the user has the specified role). If a "match" is found,
347then processing stops there and the appropriate allow/deny action is
905a3a26 350=item *
d442cc9f 351
352If none of the rules match, then access is allowed.
905a3a26 354=item *
d442cc9f 355
905a3a26 356The rules currently need to be specified in the application class
d442cc9f 357C<lib\> B<after> the C<__PACKAGE__-E<gt>setup;> line.
361=head2 Add a Method to Handle Access Violations
363By default,
365throws an exception when authorization fails. This will take the user
366to the Catalyst debug screen, or a "Please come back later" message if
367you are not using the C<-Debug> flag. This step uses the
368C<access_denied> method in order to provide more appropriate feedback to
369the user.
371Open C<lib/MyApp/Controller/> in your editor and add the
372following method:
374 =head2 access_denied
905a3a26 375
d442cc9f 376 Handle Catalyst::Plugin::Authorization::ACL access denied exceptions
905a3a26 377
d442cc9f 378 =cut
905a3a26 379
d442cc9f 380 sub access_denied : Private {
381 my ($self, $c) = @_;
905a3a26 382
d442cc9f 383 # Set the error message
384 $c->stash->{error_msg} = 'Unauthorized!';
905a3a26 385
d442cc9f 386 # Display the list
387 $c->forward('list');
388 }
905a3a26 390Then run the Catalyst development server script:
d442cc9f 391
392 $ script/
3778bcbe 394Log in as C<test02>. Once at the book list, click the "Create" link
395to try the C<form_create> action. You should receive a red
396"Unauthorized!" error message at the top of the list. (Note that in
397the example code the "Create" link code in C<root/src/books/list.tt2>
398is inside an C<IF> statement that only displays the list to
399admin-level users.) If you log in as C<test01> you should be able to
400view the C<form_create> form and add a new book.
d442cc9f 401
402When you are done, use one of the 'Logout' links (or go to the
403L<http://localhost:3000/logout> URL directly) when you are done.
406=head1 AUTHOR
408Kennedy Clark, C<>
410Please report any errors, issues or suggestions to the author. The
411most recent version of the Catalyst Tutorial can be found at
d712b826 412L<>.
d442cc9f 413
45c7830f 414Copyright 2006-2008, Kennedy Clark, under Creative Commons License
95674086 415(L<>).
d442cc9f 416