X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FAuthentication.pod;h=26707fee82c2911fc3ec8c9ae6b978d47a5a54bb;hb=d0afb3a93f0c51d32e9074957fff4e8b5aae0369;hp=453151711480b839145fa1fcd3013bf4fafc0b19;hpb=71dedf57db8d0813e63bcfc3fc3b60b469cf81a8;p=catagits%2FCatalyst-Runtime.git
diff --git a/lib/Catalyst/Manual/Tutorial/Authentication.pod b/lib/Catalyst/Manual/Tutorial/Authentication.pod
index 4531517..26707fe 100644
--- a/lib/Catalyst/Manual/Tutorial/Authentication.pod
+++ b/lib/Catalyst/Manual/Tutorial/Authentication.pod
@@ -45,7 +45,7 @@ L
=item 9
-L
+L
=back
@@ -63,8 +63,7 @@ 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.
+ svn co http://dev.catalyst.perl.org/repos/Catalyst/tags/examples/Tutorial/MyApp/5.7/Authentication MyApp
=head1 BASIC AUTHENTICATION
@@ -72,6 +71,7 @@ following command:
This section explores how to add authentication logic to a Catalyst
application.
+
=head2 Add Users and Roles to the Database
First, we add both user and role information to the database (we will
@@ -332,16 +332,14 @@ Again, notice that your "result source" classes have been "re-loaded" by Catalys
=head2 Include Authentication and Session Plugins
-Edit C and update it as follows (everything below C is new):
+Edit C and update it as follows (everything below C is new):
use Catalyst qw/
-Debug
ConfigLoader
Static::Simple
- Dumper
StackTrace
- DefaultEnd
Authentication
Authentication::Store::DBIC
@@ -355,22 +353,25 @@ Edit C and update it as follows (everything below C is
The three C plugins work together to support
Authentication while the C plugins are required to maintain
state across multiple HTTP requests. Note that there are several
-options for L (although
-L
+options for L
+(L
is generally a good choice if you are on Unix; try
L if you are on
Win32) -- consult L and
its subclasses for additional information.
+
=head2 Configure Authentication
Although C<__PACKAGE__-Econfig(name =E 'value');> is still
supported, newer Catalyst applications tend to place all configuration
information in C and automatically load this information into
-Cconfig> using the
-L plugin.
-
-Edit the C YAML and update it to match:
+Cconfig> using the
+L plugin. Here, we need
+to load several parameters that tell
+L
+where to locate information in your database. To do this, edit the
+C YAML and update it to match:
---
name: MyApp
@@ -383,7 +384,7 @@ Edit the C YAML and update it to match:
# 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' to avoid a component lookup issue in Catalyst 5.66
user_class: MyAppDB::User
# This is the name of the field in your 'users' table that contains the user's name
user_field: username
@@ -399,6 +400,7 @@ line up everything on a given 'level' with the same number of indents.
Also, be sure not to use C characters (YAML does not support them
because they are handled inconsistently across editors).
+
=head2 Add Login and Logout Controllers
Use the Catalyst create script to create two stub controller files:
@@ -411,15 +413,21 @@ you could have a C controller with both C and C
actions. Remember, Catalyst is designed to be very flexible, and leaves
such matters up to you, the designer and programmer.
-Then open C and add:
+Then open C, locate the C method (this was automatically inserted by the helpers when we
+created the Login controller above), and delete this line:
+
+ $c->response->body('Matched MyApp::Controller::Login in Login.');
- =head2 default
+Then update it to match:
+
+ =head2 index
Login logic
=cut
- sub default : Private {
+ sub index : Private {
my ($self, $c) = @_;
# Get the username and password from form
@@ -450,15 +458,34 @@ at the login page but receive an error message. If the C and
C values are not present in the form, the user will be taken
to the empty login form.
-Next, create a corresponding method in C:
-
- =head2 default
+Note that we could have used something like C;
+however, the use of C actions is discouraged because it does
+not receive path args as with other actions. The recommended practice
+is to only use C in C.
+
+Another option would be to use something like
+C (where the C<...> refers to the login
+code shown in C above). We are using C here to specifically match the URL C.
+C actions (aka, "literal actions") create URI matches relative to
+the namespace of the controller where they are defined. Although
+C supports arguments that allow relative and absolute paths to be
+defined, here we use an empty C definition to match on just the
+name of the controller itself. The method name, C, is arbitrary.
+We make the match even more specific with the C<:Args(0)> action
+modifier -- this forces the match on I C, not
+C.
+
+Next, update the corresponding method in C
+to match:
+
+ =head2 index
Logout logic
=cut
- sub default : Private {
+ sub index : Private {
my ($self, $c) = @_;
# Clear the user's state
@@ -468,6 +495,10 @@ Next, create a corresponding method in C:
$c->response->redirect($c->uri_for('/'));
}
+As with the login controller, be sure to delete the
+C<$c->response->body('Matched MyApp::Controller::Logout in Logout.');>
+line of the C.
+
=head2 Add a Login Form TT Template Page
@@ -513,11 +544,17 @@ the following method:
# Note that 'auto' runs after 'begin' but before your actions and that
# 'auto' "chain" (all from application path to most specific class are run)
+ # See the 'Actions' section of 'Catalyst::Manual::Intro' for more info.
sub auto : Private {
my ($self, $c) = @_;
- # Allow unauthenticated users to reach the login page
- if ($c->request->path =~ /login/) {
+ # Allow unauthenticated users to reach the login page. This
+ # allows anauthenticated users to reach any action in the Login
+ # controller. To lock it down to a single action, we could use:
+ # if ($c->action eq $c->controller('Login')->action_for('index'))
+ # to only allow unauthenticated access to the C action we
+ # added above.
+ if ($c->controller eq $c->controller('Login')) {
return 1;
}
@@ -555,9 +592,18 @@ C, C, and C.
=item *
-Unlike the other private C actions where only a single method
-is called for each request, I auto action along the chain of
-namespaces will be called.
+With C, C, C, C private actions, only the
+most specific action of each type will be called. For example, if you
+define a C action in your controller it will I a
+C action in your application/root controller -- I the
+action in your controller will be called.
+
+=item *
+
+Unlike the other actions where only a single method is called for each
+request, I auto action along the chain of namespaces will be
+called. Each C action will be called I.
=back
@@ -565,6 +611,7 @@ By placing the authentication enforcement code inside the C method
of C (or C), it will be
called for I request that is received by the entire application.
+
=head2 Displaying Content Only to Authenticated Users
Let's say you want to provide some information on the login page that
@@ -633,11 +680,11 @@ bottom:
Create
-Reload your browser and you should now see a "Login" link at the bottom
-of the page (as mentioned earlier, you can update template files without
-reloading the development server). Click this link to return to the
-login page. This time you I see the "You are already logged in"
-message.
+Reload your browser and you should now see a "Login" and "Create" links
+at the bottom of the page (as mentioned earlier, you can update template
+files without reloading the development server). Click the first link
+to return to the login page. This time you I see the "You are
+already logged in" message.
Finally, click the C link on the C page.
You should stay at the login page, but the message should change to "You
@@ -657,7 +704,9 @@ still transmits the passwords in cleartext to your application. We are
just avoiding the I of cleartext passwords in the database by
using a SHA-1 hash. If you are concerned about cleartext passwords
between the browser and your application, consider using SSL/TLS, made
-easy with the Catalyst plugin L.
+easy with the Catalyst plugin
+L.
+
=head2 Get a SHA-1 Hash for the Password
@@ -671,6 +720,14 @@ dirty" way to do this:
e727d1464ae12436e899a726da5b2f11d8381b26
$
+B You should probably modify this code for production use to
+not read the password from the command line. By having the script
+prompt for the cleartext password, it avoids having the password linger
+in forms such as your C<.bash_history> files (assuming you are using
+BASH as your shell). An example of such a script can be found in
+Appendix 3.
+
+
=head2 Switch to SHA-1 Password Hashes in the Database
Next, we need to change the C column of our C table to
@@ -691,6 +748,7 @@ Then use the following command to update the SQLite database:
B We are using SHA-1 hashes here, but many other hashing
algorithms are supported. See C for more information.
+
=head2 Enable SHA-1 Hash Passwords in
C
@@ -708,7 +766,8 @@ C are new, everything else is the same):
# 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
@@ -732,16 +791,23 @@ You should now be able to go to L and
login as before. When done, click the "Logout" link on the login page
(or point your browser at L).
-=head1 AUTHOR
+B If you receive the debug screen in your browser with a
+C error message,
+make sure that you are using v0.07 of
+L.
+The following command can be a useful way to quickly dump the version number
+of this module on your system:
-Kennedy Clark, C
+ perl -MCatalyst::Plugin::Authorization::ACL -e 'print $Catalyst::Plugin::Authorization::ACL::VERSION, "\n";'
-Please report any errors, issues or suggestions to the author.
-Copyright 2006, Kennedy Clark. All rights reserved.
+=head1 AUTHOR
-This library is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
+Kennedy Clark, C
-Version: .94
+Please report any errors, issues or suggestions to the author. The
+most recent version of the Catalyst Tutorial can be found at
+L.
+Copyright 2006, Kennedy Clark, under Creative Commons License
+(L).