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