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@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.