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 'MyApp::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 'MyApp::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 role to the users who have this role
 134             # See the has_many() in MyAppDB/Role.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 and/or click the "Logout" link on the book list page).  Try
 255 logging in with both C<test01> and C<test02> (both use a password
 256 of C<mypass>) and notice how the roles information updates at the
 257 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
 271 =head1 ENABLE ACL-BASED AUTHORIZATION
 272
 273 This section takes a brief look at how the
 274 L<Catalyst::Plugin::Authorization::ACL|Catalyst::Plugin::Authorization::ACL>
 275 plugin can automate much of the work required to perform role-based
 276 authorization in a Catalyst application.
 277
 278 =head2 Add the C<Catalyst::Plugin::Authorization::ACL> Plugin
 279
 280 Open C<lib/MyApp.pm> in your editor and add the following plugin to the
 281 C<use Catalyst> statement:
 282
 283     Authorization::ACL
 284
 285 Note that the remaining C<use Catalyst> plugins from earlier sections
 286 are not shown here, but they should still be included.
 287
 288 =head2 Add ACL Rules to the Application Class
 289
 290 Open C<lib/MyApp.pm> in your editor and add the following B<BELOW> the
 291 C<__PACKAGE__-E<gt>setup;> statement:
 292
 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         );
 306
 307 Each of the three statements above comprises an ACL plugin "rule".  The
 308 first two rules only allow admin-level users to create new books using
 309 the form (both the form itself and the data submission logic are
 310 protected).  The third statement allows both users and admins to delete
 311 books.  The C</books/url_create> action will continue to be protected by
 312 the "manually configured" authorization created earlier in this part of
 313 the tutorial.
 314
 315 The ACL plugin permits you to apply allow/deny logic in a variety of
 316 ways.  The following provides a basic overview of the capabilities:
 317
 318 =over 4
 319
 320 =item *
 321
 322 The ACL plugin only operates on the Catalyst "private namespace".  You
 323 are using the private namespace when you use C<Local> actions.  C<Path>,
 324 C<Regex>, and C<Global> allow you to specify actions where the path and
 325 the namespace differ -- the ACL plugin will not work in these cases.
 326
 327 =item *
 328
 329 Each rule is expressed in a separate
 330 C<__PACKAGE__-E<gt>deny_access_unless()> or
 331 C<__PACKAGE__-E<gt>allow_access_if()> line (there are several other
 332 methods that can be used for more complex policies, see the C<METHODS>
 333 portion of the
 334 L<Catalyst::Plugin::Authorization::ACL|Catalyst::Plugin::Authorization::ACL>
 335 documentation for more details).
 336
 337 =item *
 338
 339 Each rule can contain multiple roles but only a single path.
 340
 341 =item *
 342
 343 The rules are tried in order (with the "most specific" rules tested
 344 first), and processing stops at the first "match" where an allow or deny
 345 is 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,
 347 then processing stops there and the appropriate allow/deny action is
 348 taken.
 349
 350 =item *
 351
 352 If none of the rules match, then access is allowed.
 353
 354 =item *
 355
 356 The rules currently need to be specific in the application class
 357 C<lib\MyApp.pm> B<after> the C<__PACKAGE__-E<gt>setup;> line.
 358
 359 =back
 360
 361 =head2 Add a Method to Handle Access Violations
 362
 363 By default,
 364 L<Catalyst::Plugin::Authorization::ACL|Catalyst::Plugin::Authorization::ACL>
 365 throws an exception when authorization fails.  This will take the user
 366 to the Catalyst debug screen, or a "Please come back later" message if
 367 you are not using the C<-Debug> flag. This step uses the
 368 C<access_denied> method in order to provide more appropriate feedback to
 369 the user.
 370
 371 Open C<lib/MyApp/Controller/Books.pm> in your editor and add the
 372 following method:
 373
 374     =head2 access_denied
 375
 376     Handle Catalyst::Plugin::Authorization::ACL access denied exceptions
 377
 378     =cut
 379
 380     sub access_denied : Private {
 381         my ($self, $c) = @_;
 382
 383         # Set the error message
 384         $c->stash->{error_msg} = 'Unauthorized!';
 385
 386         # Display the list
 387         $c->forward('list');
 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.  The
 411 most recent version of the Catlayst Tutorial can be found at
 412 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
 413
 414 Copyright 2006, Kennedy Clark, under Creative Commons License
 415 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
 416