X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FAuthorization.pod;h=9af1ce3452f8fcac54f12b992c10b4683e068b33;hb=a4804358868199fe9ec2c98becadaa3b469a1a4f;hp=d83f5e39fb270be87b12d2562b1254894a6b7993;hpb=4d583dd846a0ffa9bd224014f89df39db957c35f;p=catagits%2FCatalyst-Runtime.git
diff --git a/lib/Catalyst/Manual/Tutorial/Authorization.pod b/lib/Catalyst/Manual/Tutorial/Authorization.pod
index d83f5e3..9af1ce3 100644
--- a/lib/Catalyst/Manual/Tutorial/Authorization.pod
+++ b/lib/Catalyst/Manual/Tutorial/Authorization.pod
@@ -1,14 +1,13 @@
=head1 NAME
-Catalyst::Manual::Tutorial::Authorization - Catalyst Tutorial Part 5: Authorization
-
+Catalyst::Manual::Tutorial::Authorization - Catalyst Tutorial - Part 5: Authorization
=head1 OVERVIEW
This is B for the Catalyst tutorial.
-L
+L
=over 4
@@ -22,7 +21,7 @@ L
=item 3
-L
+L
=item 4
@@ -46,7 +45,7 @@ L
=item 9
-L
+L
=back
@@ -54,21 +53,21 @@ 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 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.
-
+This part of the tutorial adds role-based authorization to the existing
+authentication implemented in Part 4. 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
=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:
@@ -77,9 +76,7 @@ Edit C and add C to the list:
ConfigLoader
Static::Simple
- Dumper
StackTrace
- DefaultEnd
Authentication
Authentication::Store::DBIC
@@ -94,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
@@ -107,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
@@ -123,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
@@ -136,7 +136,8 @@ Edit C and update it to match (everything from the "authorization:" l
=head2 Add Role-Specific Logic to the "Book List" Template
-Open C in your editor and add the following lines to the bottom of the file:
+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:
@@ -160,18 +161,24 @@ Open C in your editor and add the following lines to th
[% 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
-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.
+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.
-For example, we might want to restrict the "formless create" action to admin-level users by editing C and updating C to match the following code:
+For example, we might want to restrict the "formless create" action to
+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
+ Create a book with the supplied title and rating,
with manual authorization
=cut
@@ -217,44 +224,68 @@ For example, we might want to restrict the "formless create" action to admin-lev
}
-To add authorization, we simply write 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 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).
-
-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<}>.
+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
+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).
+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 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 book list page.
+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 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 C. Try:
+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
+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 done.
-
+while logged in as each user. Use one of the 'Logout' links (or go to
+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 authorization in a Catalyst application.
-
+This section takes a brief look at how the
+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