Catalyst::Authentication::Realm::SimpleDB(3pm)

1Catalyst::AuthenticatioUns:e:rReCaolnmt:r:iSbiuCmtapetldaelDPyBes(rt3l:):DAouctuhmeennttiactaitoinon::Realm::SimpleDB(3)
2
3
4

NAME

6       Catalyst::Authentication::Realm::SimpleDB - A simplified Catalyst
7       authentication configurator.
8

SYNOPSIS

10           use Catalyst qw/
11               Authentication
12           /;
13
14           __PACKAGE__->config->{'Plugin::Authentication'} =
15               {
16                   default => {
17                       class      => 'SimpleDB',
18                       user_model => 'MyApp::Schema::Users',
19                   }
20               }
21
22           # later on ...
23           $c->authenticate({ username => 'myusername',
24                              password => 'mypassword' });
25
26           my $age = $c->user->get('age');
27
28           $c->logout;
29

DESCRIPTION

31       The Catalyst::Authentication::Realm::SimpleDB provides a simple way to
32       configure Catalyst Authentication when using the most common
33       configuration of a password protected user retrieved from an SQL
34       database.
35

CONFIGURATION

37       The SimpleDB Realm class configures the Catalyst authentication system
38       based on the following:
39
40       •   Your user data is stored in a table that is accessible via
41           $c->model($cfg->{user_model});
42
43       •   Your passwords are stored in the 'password' field in your users
44           table and are not encrypted.
45
46       •   Your roles for users are stored in a separate table and are
47           directly accessible via a DBIx::Class relationship called 'roles'
48           and the text of the role is stored in a field called 'role' within
49           the role table.
50
51       •   Your user information is stored in the session once the user is
52           authenticated.
53
54       For the above usage, only one configuration option is necessary,
55       'user_model'.  user_model should contain the class name of your user
56       class. See the "PREPARATION" section for info on how to set up your
57       database for use with this module.
58
59       If your system differs from the above, some minor configuration may be
60       necessary. The options available are detailed below. These options
61       match the configuration options used by the underlying credential and
62       store modules.  More information on these options can be found in
63       Catalyst::Authentication::Credential::Password and
64       Catalyst::Authentication::Store::DBIx::Class.
65
66       user_model
67           Contains the class name (as passed to $c->model() ) of the
68           DBIx::Class schema to use as the source for user information.  This
69           config item is REQUIRED.
70
71       password_field
72           If your password field is not 'password' set this option to the
73           name of your password field.  Note that if you change this to, say
74           'users_password' you will need to use that in the authenticate
75           call:
76
77               $c->authenticate({ username => 'bob', users_password => 'foo' });
78
79       password_type
80           If the password is not stored in plaintext you will need to define
81           what format the password is in.  The common options are crypted and
82           hashed.  Crypted uses the standard unix crypt to encrypt the
83           password.  Hashed uses the Digest modules to perform password
84           hashing.
85
86       password_hash_type
87           If you use a hashed password type - this defines the type of
88           hashing. See Catalyst::Authentication::Credential::Password for
89           more details on this setting.
90
91       role_column
92           If your users roles are stored directly in your user table, set
93           this to the column name that contains your roles.  For example, if
94           your user table contains a field called 'permissions', the value of
95           role_column would be 'permissions'.  NOTE: If multiple values are
96           stored in the role column, they should be space or pipe delimited.
97
98       role_relation and role_field
99           These define an alternate role relationship name and the column
100           that holds the role's name in plain text.  See "CONFIGURATION" in
101           Catalyst::Authentication::Store::DBIx::Class for more details on
102           these settings.
103
104       use_userdata_from_session
105           This is a simple 1 / 0 setting which determines how a user's data
106           is saved / restored from the session.  If it is set to 1, the
107           user's complete information (at the time of authentication) is
108           cached between requests.  If it is set to 0, the users information
109           is loaded from the database on each request.
110

PREPARATION

112       This module makes several assumptions about the structure of your
113       database.  Below is an example of a table structure which will function
114       with this module in it's default configuration. You can use this table
115       structure as-is or add additional fields as necessary. NOTE that this
116       is the default SimpleDB configuration only. Your table structure can
117       differ significantly from this when using the DBIx::Class Store
118       directly.
119
120           --
121           -- note that you can add any additional columns you require to the users table.
122           --
123           CREATE TABLE users (
124                   id            INTEGER PRIMARY KEY,
125                   username      TEXT,
126                   password      TEXT,
127           );
128
129           CREATE TABLE roles (
130                   id   INTEGER PRIMARY KEY,
131                   role TEXT
132           );
133           CREATE TABLE user_roles (
134                   user_id INTEGER,
135                   role_id INTEGER,
136                   PRIMARY KEY (user_id, role_id)
137           );
138
139       Also, after you have loaded this table structure into your DBIx::Class
140       schema, please be sure that you have a many_to_many DBIx::Class
141       relationship defined for the users to roles relation. Your schema files
142       should contain something along these lines:
143
144       "lib/MyApp/Schema/Users.pm":
145
146           __PACKAGE__->has_many(map_user_role => 'MyApp::Schema::UserRoles', 'user_id');
147           __PACKAGE__->many_to_many(roles => 'map_user_role', 'role');
148
149       "lib/MyApp/Schema/UserRoles.pm":
150
151           __PACKAGE__->belongs_to(role => 'MyApp::Schema::Roles', 'role_id');
152

MIGRATION

154       If and when your application becomes complex enough that you need more
155       features than SimpleDB gives you access to, you can migrate to a
156       standard Catalyst Authentication configuration fairly easily.  SimpleDB
157       simply creates a standard Auth config based on the inputs you give it.
158       The config SimpleDB creates by default looks like this:
159
160           MyApp->config('Plugin::Authentication') = {
161               default => {
162                   credential => {
163                       class => 'Password',
164                       password_type => 'clear'
165                   },
166                   store => {
167                       class => 'DBIx::Class',
168                       role_relation => 'roles',
169                       role_field => 'role',
170                       use_userdata_from_session => '1',
171                       user_model => $user_model_from_simpledb_config
172                       }
173                   }
174           };
175

NAME

SYNOPSIS

DESCRIPTION

CONFIGURATION

PREPARATION

MIGRATION

SEE ALSO