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::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::Role',
role_field => 'role',
role_rel => 'map_user_role', # DBIx::Class only
user_role_user_field => 'user',
user_role_class => 'MyApp::Model::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.
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, or hashed. 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.
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.
role_field
The name of the field in "role_class" that contains the role name.
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 that contains the many-to-many linking data 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.
METHODS
user_object
Returns the DBIx::Class or Class::DBI object representing the user in the database.
INTERNAL METHODS
setup
ROLES
This section will attempt 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,
role INTEGER,
PRIMARY KEY (user, role)
);
# Class::DBI may need the following user_role table
CREATE TABLE user_role (
id INTEGER PRIMARY KEY,
user INTEGER,
role INTEGER,
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
# Example User Model
package MyApp::Model::User;
use strict;
use warnings;
use base 'MyApp::Model::DBIC';
__PACKAGE__->table( 'user' );
__PACKAGE__->add_columns( qw/id username password/ );
__PACKAGE__->set_primary_key( 'id' );
__PACKAGE__->has_many(
map_user_role => 'MyApp::Model::UserRole' => 'user' );
1;
# Example Role Model
package MyApp::Model::Role;
use strict;
use warnings;
use base 'MyApp::Model::DBIC';
__PACKAGE__->table( 'role' );
__PACKAGE__->add_columns( qw/id role/ );
__PACKAGE__->set_primary_key( 'id' );
__PACKAGE__->has_many(
map_user_role => 'MyApp::Model::UserRole' => 'role' );
1;
# Example UserRole Model
package MyApp::Model::UserRole;
use strict;
use warnings;
use base 'MyApp::Model::DBIC';
__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 => 'MyApp::Model::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
# Example User Model
package MyApp::Model::User;
use strict;
use warnings;
use base 'MyApp::Model::CDBI';
__PACKAGE__->table ( 'user' );
__PACKAGE__->columns( Primary => qw/id/ );
__PACKAGE__->columns( Essential => qw/username password/ );
1;
# Example Role Model
package MyApp::Model::Role;
use strict;
use warnings;
use base 'MyApp::Model::CDBI';
__PACKAGE__->table ( 'role' );
__PACKAGE__->columns( Primary => qw/id/ );
__PACKAGE__->columns( Essential => qw/role/ );
1;
# Example UserRole Model
package MyApp::Model::UserRole;
use strict;
use warnings;
use base 'MyApp::Model::CDBI';
__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::Role',
role_field => 'role',
user_role_class => 'MyApp::Model::UserRole',
user_role_user_field => 'user',
user_role_role_field => 'role',
};SEE ALSO
Catalyst::Plugin::Authentication, Catalyst::Plugin::Authorization::Roles
AUTHOR
Andy Grundman, <andy@hybridized.org>
COPYRIGHT
This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.