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=d0ca866fe4e340aad93e412a15b01bfb3878ecc5;hp=b1c16adefd4977cc158756003b3f7912dcc323bf;hb=94d8da411a980c822af29da44d4cbf62a72c25c1;hpb=c010ae0de590159369925f16f03dcad4732a91e6 diff --git a/lib/Catalyst/Manual/Tutorial/Authorization.pod b/lib/Catalyst/Manual/Tutorial/Authorization.pod index b1c16ad..d0ca866 100644 --- a/lib/Catalyst/Manual/Tutorial/Authorization.pod +++ b/lib/Catalyst/Manual/Tutorial/Authorization.pod @@ -57,45 +57,52 @@ L =head1 DESCRIPTION This part of the tutorial adds role-based authorization to the existing -authentication implemented in Part 4. It provides simple examples of +authentication implemented in Part 5. It provides simple examples of how to use roles in both TT templates and controller actions. The first half looks at manually configured authorization. The second half looks 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 put the plugins in the C statement if you prefer. =head2 Add Config Information for Authorization -Edit C and update it to match the following (the +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 @@ -104,39 +111,38 @@ C and C definitions are new): # Note this first definition would be the same as setting # __PACKAGE__->config->{authentication}->{realms}->{dbic} - # ->{credential} = 'Password' in lib/MyApp.pm + # ->{credential} = 'Password' in lib/MyApp.pm # # Specify that we are going to do password-based auth class Password # This is the name of the field in the users table with the # password stored in it password_field password - # We are using an unencrypted password now - password_type clear - + # Switch to more secure hashed passwords + password_type hashed + # Use the SHA-1 hashing algorithm + password_hash_type SHA-1 + # Use DBIC to retrieve username, password & role information class DBIx::Class - # This is the model object created by Catalyst::Model::DBIC - # from your schema (you created 'MyAppDB::User' but as the - # Catalyst startup debug messages show, it was loaded as - # 'MyApp::Model::MyAppDB::Users'). - # NOTE: Omit 'MyApp::Model' here just as you would when using - # '$c->model("MyAppDB::Users)' - user_class MyAppDB::Users - # This is the name of the field in your 'users' table that - # contains the user's name - id_field username + # This is the model object created by Catalyst::Model::DBIC + # from your schema (you created 'MyApp::Schema::User' but as + # the Catalyst startup debug messages show, it was loaded as + # 'MyApp::Model::DB::Users'). + # NOTE: Omit 'MyApp::Model' here just as you would when using + # '$c->model("DB::Users)' + user_class DB::Users # 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 # This is the name of field in the roles table that contains # the role information role_field role - - - - + + + + =head2 Add Role-Specific Logic to the "Book List" Template @@ -144,31 +150,32 @@ C and C definitions are new): Open C in your editor and add the following lines to the bottom of the file: -

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

+

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

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

[% # Add some simple role-specific logic to template %] [% # Use $c->check_user_roles() to check authz -%] - [% IF Catalyst.check_user_roles('user') %] + [% IF c.check_user_roles('user') %] [% # Give normal users a link for 'logout' %] - Logout + Logout [% END %] [% # Can also use $c->user->check_roles() to check authz -%] - [% IF Catalyst.check_user_roles('admin') %] + [% IF c.check_user_roles('admin') %] [% # Give admin users a link for 'create' %] - Create + 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 @@ -182,7 +189,7 @@ 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 @@ -196,30 +203,30 @@ updating C to match the following code: # Check the user's roles if ($c->check_user_roles('admin')) { - # Call create() on the book model object. Pass the table + # Call create() on the book model object. Pass the table # columns/field values we want to set as hash values - my $book = $c->model('MyAppDB::Books')->create({ + my $book = $c->model('DB::Books')->create({ title => $title, rating => $rating }); - - # Add a record to the join table for this book, mapping to + + # 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. # You won't need this if you aren't using Data::Dumper (or if - # you are running DBIC 0.06001 or greater), but adding it doesn't + # 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 { @@ -237,13 +244,14 @@ 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 2). +Part 3). 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<}>. + =head2 Try Out Authentication And Authorization Press C to kill the previous server instance (if it's still @@ -251,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 @@ -265,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 you 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. @@ -274,23 +282,25 @@ done. This section takes a brief look at how the L -plugin can automate much of the work required to perform role-based +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( @@ -319,14 +329,14 @@ ways. The following provides a basic overview of the capabilities: =over 4 -=item * +=item * The ACL plugin only operates on the Catalyst "private namespace". You are using the private namespace when you use C actions. C, C, and C allow you to specify actions where the path and the namespace differ -- the ACL plugin will not work in these cases. -=item * +=item * Each rule is expressed in a separate C<__PACKAGE__-Edeny_access_unless()> or @@ -336,11 +346,11 @@ portion of the L documentation for more details). -=item * +=item * Each rule can contain multiple roles but only a single path. -=item * +=item * The rules are tried in order (with the "most specific" rules tested first), and processing stops at the first "match" where an allow or deny @@ -349,17 +359,18 @@ is specified. Rules "fall through" if there is not a "match" (where a then processing stops there and the appropriate allow/deny action is taken. -=item * +=item * If none of the rules match, then access is allowed. -=item * +=item * -The rules currently need to be specific in the application class +The rules currently need to be specified in the application class C B the C<__PACKAGE__-Esetup;> line. =back + =head2 Add a Method to Handle Access Violations By default, @@ -389,7 +400,7 @@ following method: $c->forward('list'); } -Then run the Catalyst development server script: +Then run the Catalyst development server script: $ script/myapp_server.pl @@ -411,8 +422,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, Kennedy Clark, under Creative Commons License -(L). +Copyright 2006-2008, Kennedy Clark, under Creative Commons License +(L).