X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FAuthorization.pod;h=9af1ce3452f8fcac54f12b992c10b4683e068b33;hb=4e4cae820e184418dfcae2b388f2bd4e223532cc;hp=9a620fa7f3d55c9b663a27866abba7daa0897eb7;hpb=64ccd8a8bfbc16276c044c94702b1440c2897695;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Manual/Tutorial/Authorization.pod b/lib/Catalyst/Manual/Tutorial/Authorization.pod index 9a620fa..9af1ce3 100644 --- a/lib/Catalyst/Manual/Tutorial/Authorization.pod +++ b/lib/Catalyst/Manual/Tutorial/Authorization.pod @@ -45,7 +45,7 @@ L =item 9 -L +L =back @@ -59,21 +59,15 @@ 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. -B: Note that all of the code for this part of the tutorial can be -pulled from the Catalyst Subversion repository in one step with the -following command: - - svn checkout http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial@### - IMPORTANT: Does not work yet. Will be completed for final version. - - +You can checkout the source code for this example from the catalyst +subversion repository as per the instructions in +L =head1 BASIC AUTHORIZATION In this section you learn how to manually configure authorization. - -=head2 Update Plugins to Include Support Authorization +=head2 Update Plugins to Include Support for Authorization Edit C and add C to the list: @@ -82,9 +76,7 @@ Edit C and add C to the list: ConfigLoader Static::Simple - Dumper StackTrace - DefaultEnd Authentication Authentication::Store::DBIC @@ -99,7 +91,8 @@ Edit C and add C to the list: =head2 Add Config Information for Authorization -Edit C and update it to match (everything from the "authorization:" line down is new): +Edit C and update it to match (everything from the +"authorization:" line down is new): --- name: MyApp @@ -112,7 +105,8 @@ Edit C and update it to match (everything from the "authorization:" l # 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::User'). - # NOTE: Omit 'MyAppDB::Model' to avoid a component lookup issue in Catalyst 5.66 + # NOTE: Omit 'MyApp::Model' here just as you would when using + # '$c->model("MyAppDB::User)' user_class: MyAppDB::User # This is the name of the field in your 'users' table that contains the user's name user_field: username @@ -128,12 +122,13 @@ Edit C and update it to match (everything from the "authorization:" l # This is the model object created by Catalyst::Model::DBIC from your # schema (you created 'MyAppDB::Role' but as the Catalyst startup # debug messages show, it was loaded as 'MyApp::Model::MyAppDB::Role'). - # NOTE: Omit 'MyAppDB::Model' to avoid a component lookup issue in Catalyst 5.66 + # NOTE: Omit 'MyApp::Model' here just as you would when using + # '$c->model("MyAppDB::User)' role_class: MyAppDB::Role # The name of the field in the 'roles' table that contains the role name role_field: role - # The name of the accessor used to map a user to a role - # See the has_many() in MyAppDB/User.pm + # The name of the accessor used to map a role to the users who have this role + # See the has_many() in MyAppDB/Role.pm role_rel: map_user_role # The name of the field in the user_role table that references the user user_role_user_field: user_id @@ -166,8 +161,8 @@ lines to the bottom of the file: [% END %]

-This code displays a different combination of links depending on the roles assigned to the user.. - +This code displays a different combination of links depending on the +roles assigned to the user. =head2 Limit C to C Users @@ -175,7 +170,7 @@ C statements in TT templates simply control the output that is sent to the user's browser; it provides no real enforcement (if users know or guess the appropriate URLs, they are still perfectly free to hit any action within your application). We need to enhance the controller -logic to wrap restricted actions with role validation logic. +logic to wrap restricted actions with role-validation logic. For example, we might want to restrict the "formless create" action to admin-level users by editing C and @@ -183,7 +178,7 @@ updating C to match the following code: =head2 url_create - Create a book with the supplied title, and rating + Create a book with the supplied title and rating, with manual authorization =cut @@ -229,7 +224,7 @@ updating C to match the following code: } -To add authorization, we simply write the main code of this method in an +To add authorization, we simply wrap the main code of this method in an C statement that calls C. If the user does not have the appropriate permissions, they receive an "Unauthorized!" message. Note that we intentionally chose to display the message this @@ -244,18 +239,19 @@ 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 running) and restart it: +Press C to kill the previous server instance (if it's still +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). 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 +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 @@ -269,15 +265,13 @@ L in you browser directly) when you are done. - =head1 ENABLE ACL-BASED AUTHORIZATION This section takes a brief look at how the L -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 @@ -288,7 +282,6 @@ C statement: 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 @@ -311,7 +304,7 @@ C<__PACKAGE__-Esetup;> statement: 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 admin to delete +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. @@ -362,7 +355,6 @@ C B the C<__PACKAGE__-Esetup;> line. =back - =head2 Add a Method to Handle Access Violations By default, @@ -387,12 +379,11 @@ following method: # Set the error message $c->stash->{error_msg} = 'Unauthorized!'; - + # Display the list $c->forward('list'); } - Then run the Catalyst development server script: $ script/myapp_server.pl @@ -409,14 +400,14 @@ When you are done, use one of the 'Logout' links (or go to the L URL directly) when you are done. - =head1 AUTHOR Kennedy Clark, C -Please report any errors, issues or suggestions to the author. - -Copyright 2006, Kennedy Clark, under Creative Commons License (L). +Please report any errors, issues or suggestions to the author. The +most recent version of the Catalyst Tutorial can be found at +L. -Version: .94 +Copyright 2006, Kennedy Clark, under Creative Commons License +(L).