X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FAuthorization.pod;h=867c26ec5afa0f0a660a436ba37588a2503a7978;hb=7edc54841a8a242568f86b548bf05ebe2400de80;hp=61c5e294659c90ab7604f42de9ee3746a9631388;hpb=9ad715b3a89ba2d34123a2d0f4624302bc169f78;p=catagits%2FCatalyst-Manual.git diff --git a/lib/Catalyst/Manual/Tutorial/Authorization.pod b/lib/Catalyst/Manual/Tutorial/Authorization.pod index 61c5e29..867c26e 100644 --- a/lib/Catalyst/Manual/Tutorial/Authorization.pod +++ b/lib/Catalyst/Manual/Tutorial/Authorization.pod @@ -64,37 +64,45 @@ 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 -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 @@ -103,7 +111,7 @@ 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 @@ -118,16 +126,13 @@ C and C definitions are new): # Use DBIC to retrieve username, password & role information class DBIx::Class - # This is the model object created by Catalyst::Model::DBIC + # 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 + # 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 + # 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 @@ -145,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 @@ -183,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 @@ -197,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('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 { @@ -245,6 +251,7 @@ 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 @@ -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 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. @@ -275,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( @@ -320,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 @@ -337,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 @@ -350,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, @@ -390,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 @@ -412,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-2008, Kennedy Clark, under Creative Commons License -(L). +(L).