X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FAuthorization.pod;h=b59facf69416ee45665c48f25125ff12d8be3494;hp=c617775a2104ffe333861b4ecc7b0f24dbf8c140;hb=4e1c81079691f91c7ab2c3b65ba0d981af660e04;hpb=b411df01b40662f125aa854a7c25097bc53ad86a diff --git a/lib/Catalyst/Manual/Tutorial/Authorization.pod b/lib/Catalyst/Manual/Tutorial/Authorization.pod index c617775..b59facf 100644 --- a/lib/Catalyst/Manual/Tutorial/Authorization.pod +++ b/lib/Catalyst/Manual/Tutorial/Authorization.pod @@ -64,30 +64,36 @@ at how the ACL authorization plugin can simplify your code. You can checkout the source code for this example from the catalyst subversion repository as per the instructions in -L +L. + =head1 BASIC AUTHORIZATION In this section you learn how to manually configure authorization. + =head2 Update Plugins to Include Support for Authorization Edit C and add C to the list: - use Catalyst qw/ + __PACKAGE__->setup(qw/ -Debug ConfigLoader Static::Simple - + StackTrace - + Authentication Authorization::Roles - + Session Session::Store::FastMmap Session::State::Cookie - /; + /; + +B As discussed in MoreCatalystBasics, different versions of +C have used a variety of methods to load the plugins. +You can put the plugins in the C statement if you prefer. =head2 Add Config Information for Authorization @@ -95,6 +101,8 @@ Edit C and add C to the list: Edit C and update it to match the following (the C and C definitions are new): + # rename this file to MyApp.yml and put a : in front of "name" if + # you want to use yaml like in old versions of Catalyst name MyApp default_realm dbic @@ -125,9 +133,6 @@ C and C definitions are new): # NOTE: Omit 'MyApp::Model' here just as you would when using # '$c->model("DB::Users)' user_class DB::Users - # This is the name of the field in your 'users' table that - # contains the user's name - id_field username # This is the name of a many_to_many relation in the users # object that points to the roles for that user role_relation roles @@ -146,30 +151,31 @@ Open C in your editor and add the following lines to the bottom of the file:

Hello [% c.user.username %], you have the following roles:

- +
    [% # Dump list of roles -%] [% FOR role = c.user.roles %]
  • [% role %]
    • [% END %]
- +

[% # Add some simple role-specific logic to template %] [% # Use $c->check_user_roles() to check authz -%] [% IF c.check_user_roles('user') %] [% # Give normal users a link for 'logout' %] - Logout + User Logout [% END %] - + [% # Can also use $c->user->check_roles() to check authz -%] [% IF c.check_user_roles('admin') %] [% # Give admin users a link for 'create' %] - Create + Admin Create [% END %]

This code displays a different combination of links depending on the roles assigned to the user. + =head2 Limit C to C Users C statements in TT templates simply control the output that is sent @@ -183,18 +189,18 @@ admin-level users by editing C and updating C to match the following code: =head2 url_create - + Create a book with the supplied title and rating, with manual authorization - + =cut - - sub url_create : Local { + + sub url_create :Chained('base') :PathPart('url_create') :Args(3) { # In addition to self & context, get the title, rating & author_id args # from the URL. Note that Catalyst automatically puts extra information # after the "//check_user_roles('admin')) { # Call create() on the book model object. Pass the table @@ -203,16 +209,16 @@ updating C to match the following code: title => $title, rating => $rating }); - + # Add a record to the join table for this book, mapping to # appropriate author $book->add_to_book_authors({author_id => $author_id}); # Note: Above is a shortcut for this: # $book->create_related('book_authors', {author_id => $author_id}); - + # Assign the Book object to the stash for display in the view $c->stash->{book} = $book; - + # This is a hack to disable XSUB processing in Data::Dumper # (it's used in the view). This is a work-around for a bug in # the interaction of some versions or Perl, Data::Dumper & DBIC. @@ -220,11 +226,11 @@ updating C to match the following code: # you are running DBIC 0.06001 or greater), but adding it doesn't # hurt anything either. $Data::Dumper::Useperl = 1; - + # Set the TT template to use $c->stash->{template} = 'books/create_done.tt2'; } else { - # Provide very simple feedback to the user + # Provide very simple feedback to the user. $c->response->body('Unauthorized!'); } } @@ -238,12 +244,13 @@ way to demonstrate that TT templates will not be used if the response body has already been set. In reality you would probably want to use a technique that maintains the visual continuity of your template layout (for example, using the "status" or "error" message feature added in -Part 3). +Part 3 or C to an action that shows an "unauthorized" page). B: If you want to keep your existing C method, you can create a new copy and comment out the original by making it look like a -Pod comment. For example, put something like C<=begin> before C and C<=end> after the closing C<}>. +Pod comment. For example, put something like C<=begin> before +C and C<=end> after the closing C<}>. + =head2 Try Out Authentication And Authorization @@ -252,13 +259,13 @@ running) and restart it: $ script/myapp_server.pl -Now trying going to L and you should -be taken to the login page (you might have to C your -browser and/or click the "Logout" link on the book list page). Try -logging in with both C and C (both use a password -of C) and notice how the roles information updates at the -bottom of the "Book List" page. Also try the C link on the -book list page. +Now trying going to L and you should +be taken to the login page (you might have to C or +C your browser and/or click the "Logout" link on the book +list page). Try logging in with both C and C (both +use a password of C) and notice how the roles information +updates at the bottom of the "Book List" page. Also try the C +link on the book list page. Now the "url_create" URL will work if you are already logged in as user C, but receive an authorization failure if you are logged in as @@ -266,8 +273,8 @@ C. Try: http://localhost:3000/books/url_create/test/1/6 -while logged in as each user. Use one of the 'Logout' links (or go to -L in your browser directly) when you are +while logged in as each user. Use one of the 'Logout' links (or go to +L in your browser directly) when you are done. @@ -278,20 +285,22 @@ L plugin can automate much of the work required to perform role-based authorization in a Catalyst application. + =head2 Add the C Plugin Open C in your editor and add the following plugin to the -C statement: +C<__PACKAGE__-Esetup> statement: Authorization::ACL Note that the remaining C plugins from earlier sections are not shown here, but they should still be included. + =head2 Add ACL Rules to the Application Class Open C in your editor and add the following B the -C<__PACKAGE__-Esetup;> statement: +C<__PACKAGE__-Esetup> statement: # Authorization::ACL Rules __PACKAGE__->deny_access_unless( @@ -302,7 +311,7 @@ C<__PACKAGE__-Esetup;> statement: "/books/form_create_do", [qw/admin/], ); - __PACKAGE__->deny_access_unless( + __PACKAGE__->allow_access_if( "/books/delete", [qw/user admin/], ); @@ -311,9 +320,10 @@ Each of the three statements above comprises an ACL plugin "rule". The first two rules only allow admin-level users to create new books using the form (both the form itself and the data submission logic are protected). The third statement allows both users and admins to delete -books. The C action will continue to be protected by -the "manually configured" authorization created earlier in this part of -the tutorial. +books; letting users delete but not create book entries may sound odd in +the "real world", but this is just an example. The C +action will continue to be protected by the "manually configured" +authorization created earlier in this part of the tutorial. The ACL plugin permits you to apply allow/deny logic in a variety of ways. The following provides a basic overview of the capabilities: @@ -361,6 +371,7 @@ C B the C<__PACKAGE__-Esetup;> line. =back + =head2 Add a Method to Handle Access Violations By default, @@ -375,17 +386,17 @@ Open C in your editor and add the following method: =head2 access_denied - + Handle Catalyst::Plugin::Authorization::ACL access denied exceptions - + =cut - + sub access_denied : Private { my ($self, $c) = @_; - + # Set the error message $c->stash->{error_msg} = 'Unauthorized!'; - + # Display the list $c->forward('list'); } @@ -397,12 +408,12 @@ Then run the Catalyst development server script: Log in as C. Once at the book list, click the "Create" link to try the C action. You should receive a red "Unauthorized!" error message at the top of the list. (Note that in -the example code the "Create" link code in C +the example code the "Admin Create" link code in C is inside an C statement that only displays the list to admin-level users.) If you log in as C you should be able to view the C form and add a new book. -When you are done, use one of the 'Logout' links (or go to the +Use one of the 'Logout' links (or go to the L URL directly) when you are done. @@ -412,8 +423,8 @@ Kennedy Clark, C Please report any errors, issues or suggestions to the author. The most recent version of the Catalyst Tutorial can be found at -L. +L. Copyright 2006-2008, Kennedy Clark, under Creative Commons License -(L). +(L).