lib/Catalyst/Manual/Tutorial/Authorization.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::Authorization - Catalyst Tutorial - Part 5: Authorization
   4
   5
   6 =head1 OVERVIEW
   7
   8 This is B<Part 5 of 9> for the Catalyst tutorial.
   9
  10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
  11
  12 =over 4
  13
  14 =item 1
  15
  16 L<Introduction|Catalyst::Manual::Tutorial::Intro>
  17
  18 =item 2
  19
  20 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
  21
  22 =item 3
  23
  24 L<Basic CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
  25
  26 =item 4
  27
  28 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
  29
  30 =item 5
  31
  32 B<Authorization>
  33
  34 =item 6
  35
  36 L<Debugging|Catalyst::Manual::Tutorial::Debugging>
  37
  38 =item 7
  39
  40 L<Testing|Catalyst::Manual::Tutorial::Testing>
  41
  42 =item 8
  43
  44 L<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
  45
  46 =item 9
  47
  48 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
  49
  50 =back
  51
  52
  53
  54 =head1 DESCRIPTION
  55
  56 This part of the tutorial adds role-based authorization to the existing
  57 authentication implemented in Part 4.  It provides simple examples of
  58 how to use roles in both TT templates and controller actions.  The first
  59 half looks at manually configured authorization.  The second half looks
  60 at how the ACL authorization plugin can simplify your code.
  61
  62 B<TIP>: Note that all of the code for this part of the tutorial can be
  63 pulled from the Catalyst Subversion repository in one step with the
  64 following command:
  65
  66     svn checkout http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial@###
  67     IMPORTANT: Does not work yet.  Will be completed for final version.
  68
  69
  70 =head1 BASIC AUTHORIZATION
  71
  72 In this section you learn how to manually configure authorization.
  73
  74 =head2 Update Plugins to Include Support for Authorization
  75
  76 Edit C<lib/MyApp.pm> and add C<Authorization::Roles> to the list:
  77
  78     use Catalyst qw/
  79             -Debug
  80             ConfigLoader
  81             Static::Simple
  82
  83             Dumper
  84             StackTrace
  85             DefaultEnd
  86
  87             Authentication
  88             Authentication::Store::DBIC
  89             Authentication::Credential::Password
  90             Authorization::Roles
  91
  92             Session
  93             Session::Store::FastMmap
  94             Session::State::Cookie
  95             /;
  96
  97
  98 =head2 Add Config Information for Authorization
  99
 100 Edit C<myapp.yml> and update it to match (everything from the
 101 "authorization:" line down is new):
 102
 103     ---
 104     name: MyApp
 105     authentication:
 106         dbic:
 107             # Note this first definition would be the same as setting
 108             # __PACKAGE__->config->{authentication}->{dbic}->{user_class} = 'MyAppDB::User'
 109             # in lib/MyApp.pm (IOW, each hash key becomes a "name:" in the YAML file).
 110             #
 111             # This is the model object created by Catalyst::Model::DBIC from your
 112             # schema (you created 'MyAppDB::User' but as the Catalyst startup
 113             # debug messages show, it was loaded as 'MyApp::Model::MyAppDB::User').
 114             # NOTE: Omit 'MyAppDB::Model' to avoid a component lookup issue in Catalyst 5.66
 115             user_class: MyAppDB::User
 116             # This is the name of the field in your 'users' table that contains the user's name
 117             user_field: username
 118             # This is the name of the field in your 'users' table that contains the password
 119             password_field: password
 120             # Other options can go here for hashed passwords
 121             # Enabled hashed passwords
 122             password_type: hashed
 123             # Use the SHA-1 hashing algorithm
 124             password_hash_type: SHA-1
 125     authorization:
 126         dbic:
 127             # This is the model object created by Catalyst::Model::DBIC from your
 128             # schema (you created 'MyAppDB::Role' but as the Catalyst startup
 129             # debug messages show, it was loaded as 'MyApp::Model::MyAppDB::Role').
 130             # NOTE: Omit 'MyAppDB::Model' to avoid a component lookup issue in Catalyst 5.66
 131             role_class: MyAppDB::Role
 132             # The name of the field in the 'roles' table that contains the role name
 133             role_field: role
 134             # The name of the accessor used to map a user to a role
 135             # See the has_many() in MyAppDB/User.pm
 136             role_rel: map_user_role
 137             # The name of the field in the user_role table that references the user
 138             user_role_user_field: user_id
 139
 140
 141 =head2 Add Role-Specific Logic to the "Book List" Template
 142
 143 Open C<root/src/books/list.tt2> in your editor and add the following
 144 lines to the bottom of the file:
 145
 146     <p>Hello [% Catalyst.user.username %], you have the following roles:</p>
 147
 148     <ul>
 149       [% # Dump list of roles -%]
 150       [% FOR role = Catalyst.user.roles %]<li>[% role %]</li>[% END %]
 151     </ul>
 152
 153     <p>
 154     [% # Add some simple role-specific logic to template %]
 155     [% # Use $c->check_user_roles() to check authz -%]
 156     [% IF Catalyst.check_user_roles('user') %]
 157       [% # Give normal users a link for 'logout' %]
 158       <a href="[% Catalyst.uri_for('/logout') %]">Logout</a>
 159     [% END %]
 160
 161     [% # Can also use $c->user->check_roles() to check authz -%]
 162     [% IF Catalyst.check_user_roles('admin') %]
 163       [% # Give admin users a link for 'create' %]
 164       <a href="[% Catalyst.uri_for('form_create') %]">Create</a>
 165     [% END %]
 166     </p>
 167
 168 This code displays a different combination of links depending on the
 169 roles assigned to the user.
 170
 171 =head2 Limit C<Books::add> to C<admin> Users
 172
 173 C<IF> statements in TT templates simply control the output that is sent
 174 to the user's browser; it provides no real enforcement (if users know or
 175 guess the appropriate URLs, they are still perfectly free to hit any
 176 action within your application).  We need to enhance the controller
 177 logic to wrap restricted actions with role-validation logic.
 178
 179 For example, we might want to restrict the "formless create" action to
 180 admin-level users by editing C<lib/MyApp/Controller/Books.pm> and
 181 updating C<url_create> to match the following code:
 182
 183     =head2 url_create
 184
 185     Create a book with the supplied title and rating,
 186     with manual authorization
 187
 188     =cut
 189
 190     sub url_create : Local {
 191         # In addition to self & context, get the title, rating & author_id args
 192         # from the URL.  Note that Catalyst automatically puts extra information
 193         # after the "/<controller_name>/<action_name/" into @_
 194         my ($self, $c, $title, $rating, $author_id) = @_;
 195
 196         # Check the user's roles
 197         if ($c->check_user_roles('admin')) {
 198             # Call create() on the book model object. Pass the table
 199             # columns/field values we want to set as hash values
 200             my $book = $c->model('MyAppDB::Book')->create({
 201                     title   => $title,
 202                     rating  => $rating
 203                 });
 204
 205             # Add a record to the join table for this book, mapping to
 206             # appropriate author
 207             $book->add_to_book_authors({author_id => $author_id});
 208             # Note: Above is a shortcut for this:
 209             # $book->create_related('book_authors', {author_id => $author_id});
 210
 211             # Assign the Book object to the stash for display in the view
 212             $c->stash->{book} = $book;
 213
 214             # This is a hack to disable XSUB processing in Data::Dumper
 215             # (it's used in the view).  This is a work-around for a bug in
 216             # the interaction of some versions or Perl, Data::Dumper & DBIC.
 217             # You won't need this if you aren't using Data::Dumper (or if
 218             # you are running DBIC 0.06001 or greater), but adding it doesn't
 219             # hurt anything either.
 220             $Data::Dumper::Useperl = 1;
 221
 222             # Set the TT template to use
 223             $c->stash->{template} = 'books/create_done.tt2';
 224         } else {
 225             # Provide very simple feedback to the user
 226             $c->response->body('Unauthorized!');
 227         }
 228     }
 229
 230
 231 To add authorization, we simply wrap the main code of this method in an
 232 C<if> statement that calls C<check_user_roles>.  If the user does not
 233 have the appropriate permissions, they receive an "Unauthorized!"
 234 message.  Note that we intentionally chose to display the message this
 235 way to demonstrate that TT templates will not be used if the response
 236 body has already been set.  In reality you would probably want to use a
 237 technique that maintains the visual continuity of your template layout
 238 (for example, using the "status" or "error" message feature added in
 239 Part 2).
 240
 241 B<TIP>: If you want to keep your existing C<url_create> method, you can
 242 create a new copy and comment out the original by making it look like a
 243 Pod comment.  For example, put something like C<=begin> before C<sub add
 244 : Local {> and C<=end> after the closing C<}>.
 245
 246 =head2 Try Out Authentication And Authorization
 247
 248 Press C<Ctrl-C> to kill the previous server instance (if it's still
 249 running) and restart it:
 250
 251     $ script/myapp_server.pl
 252
 253 Now trying going to L<http://localhost:3000/books/list> and you should
 254 be taken to the login page (you might have to C<Shift+Reload> your
 255 browser).  Try logging in with both C<test01> and C<test02> (both use a
 256 password of C<mypass>) and notice how the roles information updates at
 257 the bottom of the "Book List" page. Also try the C<Logout> link on the
 258 book list page.
 259
 260 Now the "url_create" URL will work if you are already logged in as user
 261 C<test01>, but receive an authorization failure if you are logged in as
 262 C<test02>.  Try:
 263
 264     http://localhost:3000/books/url_create/test/1/6
 265
 266 while logged in as each user.  Use one of the 'Logout' links (or go to
 267 L<http://localhost:3000/logout> in you browser directly) when you are
 268 done.
 269
 270 =head1 ENABLE ACL-BASED AUTHORIZATION
 271
 272 This section takes a brief look at how the
 273 L<Catalyst::Plugin::Authorization::ACL> plugin can automate much of the
 274 work required to perform role-based authorization in a Catalyst
 275 application.
 276
 277 =head2 Add the C<Catalyst::Plugin::Authorization::ACL> Plugin
 278
 279 Open C<lib/MyApp.pm> in your editor and add the following plugin to the
 280 C<use Catalyst> statement:
 281
 282     Authorization::ACL
 283
 284 Note that the remaining C<use Catalyst> plugins from earlier sections
 285 are not shown here, but they should still be included.
 286
 287 =head2 Add ACL Rules to the Application Class
 288
 289 Open C<lib/MyApp.pm> in your editor and add the following B<BELOW> the
 290 C<__PACKAGE__-E<gt>setup;> statement:
 291
 292     # Authorization::ACL Rules
 293     __PACKAGE__->deny_access_unless(
 294             "/books/form_create",
 295             [qw/admin/],
 296         );
 297     __PACKAGE__->deny_access_unless(
 298             "/books/form_create_do",
 299             [qw/admin/],
 300         );
 301     __PACKAGE__->deny_access_unless(
 302             "/books/delete",
 303             [qw/user admin/],
 304         );
 305
 306 Each of the three statements above comprises an ACL plugin "rule".  The
 307 first two rules only allow admin-level users to create new books using
 308 the form (both the form itself and the data submission logic are
 309 protected).  The third statement allows both users and admin to delete
 310 books.  The C</books/url_create> action will continue to be protected by
 311 the "manually configured" authorization created earlier in this part of
 312 the tutorial.
 313
 314 The ACL plugin permits you to apply allow/deny logic in a variety of
 315 ways.  The following provides a basic overview of the capabilities:
 316
 317 =over 4
 318
 319 =item *
 320
 321 The ACL plugin only operates on the Catalyst "private namespace".  You
 322 are using the private namespace when you use C<Local> actions.  C<Path>,
 323 C<Regex>, and C<Global> allow you to specify actions where the path and
 324 the namespace differ -- the ACL plugin will not work in these cases.
 325
 326 =item *
 327
 328 Each rule is expressed in a separate
 329 C<__PACKAGE__-E<gt>deny_access_unless()> or
 330 C<__PACKAGE__-E<gt>allow_access_if()> line (there are several other
 331 methods that can be used for more complex policies, see the C<METHODS>
 332 portion of the
 333 L<Catalyst::Plugin::Authorization::ACL|Catalyst::Plugin::Authorization::ACL>
 334 documentation for more details).
 335
 336 =item *
 337
 338 Each rule can contain multiple roles but only a single path.
 339
 340 =item *
 341
 342 The rules are tried in order (with the "most specific" rules tested
 343 first), and processing stops at the first "match" where an allow or deny
 344 is specified.  Rules "fall through" if there is not a "match" (where a
 345 "match" means the user has the specified role).  If a "match" is found,
 346 then processing stops there and the appropriate allow/deny action is
 347 taken.
 348
 349 =item *
 350
 351 If none of the rules match, then access is allowed.
 352
 353 =item *
 354
 355 The rules currently need to be specific in the application class
 356 C<lib\MyApp.pm> B<after> the C<__PACKAGE__-E<gt>setup;> line.
 357
 358 =back
 359
 360 =head2 Add a Method to Handle Access Violations
 361
 362 By default,
 363 L<Catalyst::Plugin::Authorization::ACL>
 364 throws an exception when authorization fails.  This will take the user
 365 to the Catalyst debug screen, or a "Please come back later" message if
 366 you are not using the C<-Debug> flag. This step uses the
 367 C<access_denied> method in order to provide more appropriate feedback to
 368 the user.
 369
 370 Open C<lib/MyApp/Controller/Books.pm> in your editor and add the
 371 following method:
 372
 373     =head2 access_denied
 374
 375     Handle Catalyst::Plugin::Authorization::ACL access denied exceptions
 376
 377     =cut
 378
 379     sub access_denied : Private {
 380         my ($self, $c) = @_;
 381
 382         # Set the error message
 383         $c->stash->{error_msg} = 'Unauthorized!';
 384
 385         # Display the list
 386         $c->forward('list');
 387     }
 388
 389
 390 Then run the Catalyst development server script:
 391
 392     $ script/myapp_server.pl
 393
 394 Log in as C<test02>.  Once at the book list, click the "Create" link to
 395 try the C<form_create> action.  You should receive a red "Unauthorized!"
 396 error message at the top of the list.  (Note that in reality you would
 397 probably want to place the "Create" link code in
 398 C<root/src/books/list.tt2> inside an C<IF> statement that only displays
 399 the list to admin-level users.)  If you log in as C<test01> you should
 400 be able to view the C<form_create> form and add a new book.
 401
 402 When you are done, use one of the 'Logout' links (or go to the
 403 L<http://localhost:3000/logout> URL directly) when you are done.
 404
 405
 406 =head1 AUTHOR
 407
 408 Kennedy Clark, C<hkclark@gmail.com>
 409
 410 Please report any errors, issues or suggestions to the author.
 411
 412 Copyright 2006, Kennedy Clark, under Creative Commons License
 413 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
 414
 415 Version: .94
 416