[Catalyst-commits] r6325 -
trunk/Catalyst-Plugin-Authentication-Store-DBIC
bricas at dev.catalyst.perl.org
bricas at dev.catalyst.perl.org
Fri Apr 27 03:05:27 GMT 2007
Author: bricas
Date: 2007-04-27 03:05:26 +0100 (Fri, 27 Apr 2007)
New Revision: 6325
Added:
trunk/Catalyst-Plugin-Authentication-Store-DBIC/Makefile.PL
trunk/Catalyst-Plugin-Authentication-Store-DBIC/README
Removed:
trunk/Catalyst-Plugin-Authentication-Store-DBIC/Build.PL
Modified:
trunk/Catalyst-Plugin-Authentication-Store-DBIC/Changes
Log:
switch to Module::Install
Deleted: trunk/Catalyst-Plugin-Authentication-Store-DBIC/Build.PL
===================================================================
--- trunk/Catalyst-Plugin-Authentication-Store-DBIC/Build.PL 2007-04-27 00:59:50 UTC (rev 6324)
+++ trunk/Catalyst-Plugin-Authentication-Store-DBIC/Build.PL 2007-04-27 02:05:26 UTC (rev 6325)
@@ -1,24 +0,0 @@
-use strict;
-use Module::Build;
-
-my $build = Module::Build->new(
- create_makefile_pl => 'traditional',
- license => 'perl',
- module_name => 'Catalyst::Plugin::Authentication::Store::DBIC',
- requires => {
- 'Catalyst' => '5.49',
- 'Catalyst::Plugin::Authentication' => '0.06',
- 'Set::Object' => '1.14',
- 'DBI' => '0',
- },
- recommends => {
- 'Catalyst::Plugin::Authorization::Roles' => '0.03',
- 'Catalyst::Plugin::Session::State::Cookie' => '0.02',
- 'DBIx::Class' => 0,
- 'Class::DBI' => 0,
- 'Test::WWW::Mechanize::Catalyst' => 0,
- },
- create_readme => 1,
-);
-$build->create_build_script;
-
Modified: trunk/Catalyst-Plugin-Authentication-Store-DBIC/Changes
===================================================================
--- trunk/Catalyst-Plugin-Authentication-Store-DBIC/Changes 2007-04-27 00:59:50 UTC (rev 6324)
+++ trunk/Catalyst-Plugin-Authentication-Store-DBIC/Changes 2007-04-27 02:05:26 UTC (rev 6325)
@@ -1,7 +1,8 @@
Revision history for Perl extension Catalyst::Plugin::Authentication::Store::DBIC
- - Made $c->user->id return the first field of user_field, rather than whatever was passed in.
+ - Made $c->user->id return the first field of user_field, rather than whatever was passed in.
- Lazy fetching of user_obj
+ - Switch to Module::Install
0.07 2006-06-30 01:08:47
- make the User class stringify to the user id
Added: trunk/Catalyst-Plugin-Authentication-Store-DBIC/Makefile.PL
===================================================================
--- trunk/Catalyst-Plugin-Authentication-Store-DBIC/Makefile.PL (rev 0)
+++ trunk/Catalyst-Plugin-Authentication-Store-DBIC/Makefile.PL 2007-04-27 02:05:26 UTC (rev 6325)
@@ -0,0 +1,32 @@
+use inc::Module::Install 0.65;
+
+name 'Catalyst-Plugin-Authentication-Store-DBIC';
+all_from 'lib/Catalyst/Plugin/Authentication/Store/DBIC.pm';
+
+requires 'Catalyst::Runtime';
+requires 'Catalyst::Plugin::Authentication' => '0.06';
+requires 'Set::Object' => '1.14';
+requires 'DBI';
+
+feature 'Roles support',
+ -default => 1,
+ 'Catalyst::Plugin::Authorization::Roles' => '0.03';
+
+feature 'Cookie support',
+ -default => 1,
+ 'Catalyst::Plugin::Session::State::Cookie' => '0.02';
+
+feature 'DBIx::Class support',
+ -default => 1,
+ 'DBIx::Class' => 0;
+
+feature 'Class::DBI support',
+ -default => 0,
+ 'Class::DBI' => 0;
+
+feature 'Test::WWW::Mechanize::Catalyst for testing',
+ -default => 0,
+ 'Test::WWW::Mechanize::Catalyst' => 0;
+
+auto_install;
+WriteAll;
Added: trunk/Catalyst-Plugin-Authentication-Store-DBIC/README
===================================================================
--- trunk/Catalyst-Plugin-Authentication-Store-DBIC/README (rev 0)
+++ trunk/Catalyst-Plugin-Authentication-Store-DBIC/README 2007-04-27 02:05:26 UTC (rev 6325)
@@ -0,0 +1,363 @@
+NAME
+ Catalyst::Plugin::Authentication::Store::DBIC - Authentication and
+ authorization against a DBIx::Class or Class::DBI model.
+
+SYNOPSIS
+ use Catalyst qw/
+ Authentication
+ Authentication::Store::DBIC
+ Authentication::Credential::Password
+ Authorization::Roles # if using roles
+ /;
+
+ # Authentication
+ __PACKAGE__->config->{authentication}{dbic} = {
+ user_class => 'MyApp::Model::DB::User',
+ user_field => 'username',
+ password_field => 'password',
+ password_type => 'hashed',
+ password_hash_type => 'SHA-1',
+ };
+
+ # Authorization using a many-to-many role relationship
+ # For more detailed instructions on setting up role-based auth, please
+ # see the section below titled L<Roles>.
+ __PACKAGE__->config->{authorization}{dbic} = {
+ role_class => 'MyApp::Model::DB::Role',
+ role_field => 'role',
+ role_rel => 'map_user_role', # DBIx::Class only
+ user_role_user_field => 'user',
+ user_role_class => 'MyApp::Model::DB::UserRole', # Class::DBI only
+ user_role_role_field => 'role', # Class::DBI only
+ };
+
+ # log a user in
+ sub login : Global {
+ my ( $self, $c ) = @_;
+
+ $c->login( $c->req->param("email"), $c->req->param("password"), );
+ }
+
+ # verify a role
+ if ( $c->check_user_roles( 'admin' ) ) {
+ $model->delete_everything;
+ }
+
+DESCRIPTION
+ This plugin uses a DBIx::Class (or Class::DBI) object to authenticate a
+ user.
+
+AUTHENTICATION CONFIGURATION
+ Authentication is configured by setting an authentication->{dbic} hash
+ reference in your application's config method. The following
+ configuration options are supported.
+
+ user_class
+ The name of the class that represents a user object. Can be the full
+ class name, or just the model name (i.e. the part after "MyApp::Model").
+ If it is a DBIC class, will automatically save and use the resultset
+ from the DBIC schema.
+
+ user_field
+ The name of the column holding the user identifier (defaults to "user")
+
+ password_field
+ The name of the column holding the user's password (defaults to
+ "password")
+
+ password_type
+ The type of password your user object stores. One of: clear, crypted,
+ hashed, or salted_hash. Defaults to clear.
+
+ password_hash_type
+ If using a password_type of hashed, this option specifies the hashing
+ method being used. Any hashing method supported by the Digest module may
+ be used.
+
+ password_pre_salt
+ Use this option if your passwords are hashed with a prefix salt value.
+
+ password_post_salt
+ Use this option if your passwords are hashed with a postfix salt value.
+
+ password_salt_len
+ Use this option to specify the salt length for salted_hash passwords
+ (defaults to 0).
+
+ auto_create_user
+ If this option is set, when a user is not found, an "auto_create" method
+ will be called on your "user_class" with the arguments that were passed
+ to "get_user" in Catalyst::Plugin::Authentication::Store::DBIC::Backend.
+ If it returns true, it is assumed that a user corresponding to the
+ arguments has been created, and the user will be looked up again.
+
+ session_data_field
+ This option should be set to the name of an accessor in your model class
+ which can store and retreive a hashref. If this option is set, the user
+ object will advertise that it supports the feature "session_data", and
+ other code will be able to use the "$c->session_data" accessor. This can
+ be used in combination with other plugins that can make use of the
+ "session_data" feature, like Catalyst::Plugin::Session::PerUser. See the
+ documentation for one of those modules to see how to use this
+ functionality from a controller.
+
+ You can set up automatic inflation and deflation for the chosen field to
+ deal with the hash reference. Here's an example of how to do that in
+ DBIC with a "TEXT" column, MIME::Base64, and Storable:
+
+ package MySchema::Users;
+ use base qw/DBIx::Class/;
+ use Storable qw/freeze thaw/;
+ use MIME::Base64;
+
+ # define table, columns, primary key, etc. here
+
+ __PACKAGE__->inflate_column(
+ session_data => {
+ inflate => sub { thaw(decode_base64(shift)) },
+ deflate => sub { encode_base64(freeze(shift)) },
+ }
+ );
+
+ catalyst_user_class
+ If using a plain model class which has username and password fields is
+ not working for you, because you have more complex objects, or you need
+ to do something else odd to fetch those values or your role fields, you
+ can subclass Catalyst::Plugin::Authentication::Store::DBIC::User, and
+ supply your class name here.
+
+AUTHORIZATION CONFIGURATION
+ Role-based authorization is configured by setting an
+ authorization->{dbic} hash reference in your application's config
+ method. The following options are supported. For more detailed
+ instructions on setting up roles, please see the section below titled
+ Roles.
+
+ role_class
+ The name of the class that contains the list of roles. Can be the full
+ class name, or just the model name (i.e. the part after "MyApp::Model").
+ If it is a DBIC class, will automatically save and use the resultset
+ from the DBIC schema.
+
+ role_field
+ The name of the field in role_class that contains the role name. The
+ role name is typically a text value like "admin".
+
+ role_rel
+ DBIx::Class models only. This field specifies the name of the
+ relationship in role_class that refers to the mapping table between
+ users and roles. Using this relationship, DBIx::Class models can
+ retrieve the list of roles for a user in a single SQL statement using a
+ join.
+
+ user_role_class
+ Class::DBI models only. The name of the class for the many-to-many
+ linking table between users and roles.
+
+ user_role_user_field
+ The name of the field in user_role_class that contains the user id. This
+ is required for both DBIx::Class and Class::DBI.
+
+ user_role_role_field
+ Class::DBI models only. The name of the field in user_role_class that
+ contains the role id, which is a foreign key referencing the primary key
+ of the table corresponding to "role_class".
+
+METHODS
+ obj
+ You can get the DBIx::Class or Class::DBI row object corresponding to
+ the current user by calling "$c->user->obj". You can also get the value
+ of an individual column with "$c->user->column_name", assuming it does
+ not conflict with an existing method in
+ <Catalyst::Plugin::Authentication::Store::DBIC.
+
+ Note: The earlier methods of "$c->user_object" and "$c->user->user"
+ still work, but are no longer recommended. The new API is cleaner and
+ easier to use.
+
+INTERNAL METHODS
+ setup
+ setup_finished
+ Finalizes the setup of the plugin by filling in the "user_class" and
+ "role_class" config values with the appropriate DBIx::Class resultsets.
+ Does nothing if you are using Class::DBI.
+
+ROLES
+ This section attempts to provide detailed instructions for configuring
+ role-based authorization in your application.
+
+ Database Schema
+ The basic database structure for roles consists of the following 3
+ tables. This syntax is for SQLite, but can be easily adapted to other
+ databases.
+
+ CREATE TABLE user (
+ id INTEGER PRIMARY KEY,
+ username TEXT,
+ password TEXT
+ );
+
+ CREATE TABLE role (
+ id INTEGER PRIMARY KEY,
+ role TEXT
+ );
+
+ # DBIx::Class can handle multiple primary keys
+ CREATE TABLE user_role (
+ user INTEGER REFERENCES user,
+ role INTEGER REFERENCES role,
+ PRIMARY KEY (user, role)
+ );
+
+ # Class::DBI may need the following user_role table
+ CREATE TABLE user_role (
+ id INTEGER PRIMARY KEY,
+ user INTEGER REFERENCES user,
+ role INTEGER REFERENCES role,
+ UNIQUE (user, role)
+ );
+
+ DBIx::Class
+ For best performance when using roles, DBIx::Class models are
+ recommended. By using DBIx::Class you will benefit from optimized SQL
+ using joins that can retrieve roles for a user with a single SQL
+ statement.
+
+ The steps for setting up roles with DBIx::Class are:
+
+ 1. Create Model classes and define relationships
+ package MyApp::Model::DB;
+ use strict;
+ use base 'Catalyst::Model::DBIC::Schema';
+ __PACKAGE__->config(
+ schema_class => 'MyApp::Schema',
+ connect_info => [ ... ],
+ );
+
+ 1;
+
+ package MyApp::Schema;
+ use strict;
+ use base 'DBIx::Class::Schema';
+
+ __PACKAGE__->load_classes;
+
+ 1;
+
+ package MyApp::Schema::User;
+ use strict;
+ use base 'DBIx::Class';
+
+ __PACKAGE__->load_components( qw/ Core / );
+ __PACKAGE__->table( 'user' );
+ __PACKAGE__->add_columns( qw/id username password/ );
+ __PACKAGE__->set_primary_key( 'id' );
+
+ __PACKAGE__->has_many(
+ map_user_role => 'MyApp::Schema::UserRole' => 'user' );
+
+ 1;
+
+ package MyApp::Schema::Role;
+ use strict;
+ use base 'DBIx::Class';
+
+ __PACKAGE__->load_components( qw/ Core / );
+ __PACKAGE__->table( 'role' );
+ __PACKAGE__->add_columns( qw/id role/ );
+ __PACKAGE__->set_primary_key( 'id' );
+
+ __PACKAGE__->has_many(
+ map_user_role => 'MyApp::Schema::UserRole' => 'role' );
+
+ 1;
+
+ package MyApp::Schema::UserRole;
+ use strict;
+ use base 'DBIx::Class';
+
+ __PACKAGE__->load_components( qw/ Core / );
+ __PACKAGE__->table( 'user_role' );
+ __PACKAGE__->add_columns( qw/user role/ );
+ __PACKAGE__->set_primary_key( qw/user role/ );
+
+ 1;
+
+ 2. Specify authorization configuration settings
+ For the above DBIx::Class model classes, the configuration would look
+ like this:
+
+ __PACKAGE__->config->{authorization}{dbic} = {
+ role_class => 'DB::Role',
+ role_field => 'role',
+ role_rel => 'map_user_role',
+ user_role_user_field => 'user',
+ };
+
+ Class::DBI
+ Class::DBI models are also supported but require slightly more
+ configuration. Performance will also suffer as more SQL statements must
+ be run to retrieve all roles for a user.
+
+ The steps for setting up roles with Class::DBI are:
+
+ 1. Create Model classes
+ package MyApp::Model::DB;
+ use strict;
+ use base 'Class::DBI';
+ __PACKAGE__->connection(...);
+
+ package MyApp::Model::DB::User;
+ use strict;
+ use base 'MyApp::Model::DB';
+
+ __PACKAGE__->table ( 'user' );
+ __PACKAGE__->columns( Primary => qw/id/ );
+ __PACKAGE__->columns( Essential => qw/username password/ );
+
+ 1;
+
+ package MyApp::Model::DB::Role;
+ use strict;
+ use base 'MyApp::Model::DB';
+
+ __PACKAGE__->table ( 'role' );
+ __PACKAGE__->columns( Primary => qw/id/ );
+ __PACKAGE__->columns( Essential => qw/role/ );
+
+ 1;
+
+ package MyApp::Model::DB::UserRole;
+ use strict;
+ use base 'MyApp::Model::DB';
+
+ __PACKAGE__->table ( 'user_role' );
+ __PACKAGE__->columns( Primary => qw/id/ );
+ __PACKAGE__->columns( Essential => qw/user role/ );
+
+ 1;
+
+ 2. Specify authorization configuration settings
+ For the above Class::DBI model classes, the configuration would look
+ like this:
+
+ __PACKAGE__->config->{authorization}{dbic} = {
+ role_class => 'MyApp::Model::DB::Role',
+ role_field => 'role',
+ user_role_class => 'MyApp::Model::DB::UserRole',
+ user_role_user_field => 'user',
+ user_role_role_field => 'role',
+ };
+
+SEE ALSO
+ Catalyst::Plugin::Authentication, Catalyst::Plugin::Authorization::Roles
+
+AUTHORS
+ David Kamholz, <dkamholz at cpan.org>
+
+ Andy Grundman
+
+COPYRIGHT
+ This program is free software, you can redistribute it and/or modify it
+ under the same terms as Perl itself.
+
More information about the Catalyst-commits
mailing list