Catalyst::Plugin::Authentication::Store::DBIC - **DEPRECATED** Authentication and authorization against a DBIx::Class or Class::DBI model.
This store has been deprecated in favour of Catalyst::Authentication::Store::DBIx::Class. Please do not use this plugin for new development.
use Catalyst qw/ Authentication Authentication::Store::DBIC Authentication::Credential::Password Authorization::Roles # if using roles /; # Authentication __PACKAGE__->config->{authentication}{dbic} = { user_class => '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 => 'DB::Role', role_field => 'role', role_rel => 'map_user_role', # DBIx::Class only user_role_user_field => 'user', user_role_class => '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; }
This plugin uses a DBIx::Class (or Class::DBI) object to authenticate a user.
Authentication is configured by setting an authentication->{dbic} hash reference in your application's config method. The following configuration options are supported.
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.
MyApp::Model
The name of the column holding the user identifier (defaults to user)
user
The name of the column holding the user's password (defaults to password)
password
The type of password your user object stores. One of: clear, crypted, hashed, or salted_hash. Defaults to clear.
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.
Use this option if your passwords are hashed with a prefix salt value.
Use this option if your passwords are hashed with a postfix salt value.
Use this option to specify the salt length for salted_hash passwords (defaults to 0).
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.
auto_create
user_class
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.
session_data
$c->session_data
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:
TEXT
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)) }, } );
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.
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.
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.
The name of the field in role_class that contains the role name. The role name is typically a text value like admin.
admin
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.
Class::DBI models only. The name of the class for the many-to-many linking table between users and roles.
The name of the field in user_role_class that contains the user id. This is required for both DBIx::Class and Class::DBI.
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.
role_class
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.
$c->user->obj
$c->user->column_name
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.
$c->user_object
$c->user->user
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.
This section attempts to provide detailed instructions for configuring role-based authorization in your application.
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) );
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:
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;
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 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:
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;
For the above Class::DBI model classes, the configuration would look like this:
__PACKAGE__->config->{authorization}{dbic} = { role_class => 'DB::Role', role_field => 'role', user_role_class => 'DB::UserRole', user_role_user_field => 'user', user_role_role_field => 'role', };
Catalyst::Plugin::Authentication, Catalyst::Plugin::Authorization::Roles
David Kamholz, <dkamholz@cpan.org>
Andy Grundman
This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.
To install Catalyst::Plugin::Authentication::Store::DBIC, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Catalyst::Plugin::Authentication::Store::DBIC
CPAN shell
perl -MCPAN -e shell install Catalyst::Plugin::Authentication::Store::DBIC
For more information on module installation, please visit the detailed CPAN module installation guide.