README

   1 NAME
   2     Catalyst::Plugin::Authentication::Store::DBIx::Class - A storage class
   3     for Catalyst Authentication using DBIx::Class
   4
   5 VERSION
   6     This documentation refers to version 0.10.
   7
   8 SYNOPSIS
   9         use Catalyst qw/
  10                         Authentication
  11                         Authorization::Roles/;
  12
  13         __PACKAGE__->config->{authentication} =
  14                         {
  15                             default_realm => 'members',
  16                             realms => {
  17                                 members => {
  18                                     credential => {
  19                                         class => 'Password',
  20                                         password_field => 'password',
  21                                         password_type => 'clear'
  22                                     },
  23                                     store => {
  24                                         class => 'DBIx::Class',
  25                                         user_class => 'MyApp::Users',
  26                                         id_field => 'user_id',
  27                                         role_relation => 'roles',
  28                                         role_field => 'rolename',
  29                                     }
  30                                 }
  31                             }
  32                         };
  33
  34         # Log a user in:
  35
  36         sub login : Global {
  37             my ( $self, $c ) = @_;
  38
  39             $c->authenticate({
  40                               username => $c->req->params->username,
  41                               password => $c->req->params->password,
  42                               status => [ 'registered', 'loggedin', 'active']
  43                               }))
  44         }
  45
  46         # verify a role
  47
  48         if ( $c->check_user_roles( 'editor' ) ) {
  49             # do editor stuff
  50         }
  51
  52 DESCRIPTION
  53     The Catalyst::Plugin::Authentication::Store::DBIx::Class class provides
  54     access to authentication information stored in a database via
  55     DBIx::Class.
  56
  57 CONFIGURATION
  58     The DBIx::Class authentication store is activated by setting the store
  59     config's class element to DBIx::Class as shown above. See the
  60     Catalyst::Plugin::Authentication documentation for more details on
  61     configuring the store.
  62
  63     The DBIx::Class storage module has several configuration options
  64
  65         __PACKAGE__->config->{authentication} =
  66                         {
  67                             default_realm => 'members',
  68                             realms => {
  69                                 members => {
  70                                     credential => {
  71                                         # ...
  72                                     },
  73                                     store => {
  74                                         class => 'DBIx::Class',
  75                                         user_class => 'MyApp::Users',
  76                                         id_field => 'user_id',
  77                                         role_relation => 'roles',
  78                                         role_field => 'rolename',
  79                                         ignore_fields_in_find => [ 'remote_name' ]
  80                                     }
  81                                     }
  82                             }
  83                         };
  84
  85     class
  86         Class is part of the core Catalyst::Authentication::Plugin module,
  87         it contains the class name of the store to be used.
  88
  89     user_class
  90         Contains the class name (as passed to $c->model()) of the
  91         DBIx::Class schema to use as the source for user information. This
  92         config item is REQUIRED.
  93
  94     id_field
  95         Contains the field name containing the unique identifier for a user.
  96         This is used when storing and retrieving a user from the session.
  97         The value in this field should correspond to a single user in the
  98         database. Defaults to 'id'.
  99
 100     role_column
 101         If your role information is stored in the same table as the rest of
 102         your user information, this item tells the module which field
 103         contains your role information. The DBIx::Class authentication store
 104         expects the data in this field to be a series of role names
 105         separated by some combination of spaces, commas or pipe characters.
 106
 107     role_relation
 108         If your role information is stored in a separate table, this is the
 109         name of the relation that will lead to the roles the user is in. If
 110         this is specified then a role_field is also required. Also when
 111         using this method it is expected that your role table will return
 112         one row for each role the user is in.
 113
 114     role_field
 115         This is the name of the field in the role table that contains the
 116         string identifying the role.
 117
 118     ignore_fields_in_find
 119         This item is an array containing fields that may be passed to the
 120         $c->authenticate() routine (and therefore find_user in the storage
 121         class), but which should be ignored when creating the DBIx::Class
 122         search to retrieve a user. This makes it possible to avoid problems
 123         when a credential requires an authinfo element whose name overlaps
 124         with a column name in your users table. If this doesn't make sense
 125         to you, you probably don't need it.
 126
 127     store_user_class
 128         This allows you to override the authentication user class that the
 129         DBIx::Class store module uses to perform it's work. Most of the work
 130         done in this module is actually done by the user class,
 131         Catalyst::Plugin::Authentication::Store::DBIx::Class::User, so
 132         overriding this doesn't make much sense unless you are using your
 133         own class to extend the functionality of the existing class. Chances
 134         are you do not want to set this.
 135
 136 USAGE
 137     The Catalyst::Plugin::Authentication::Store::DBIx::Class storage module
 138     is not called directly from application code. You interface with it
 139     through the $c->authenticate() call.
 140
 141     There are three methods you can use to retrieve information from the
 142     DBIx::Class storage module. They are Simple retrieval, and the advanced
 143     retrieval methods Searchargs and Resultset.
 144
 145   Simple Retrieval
 146     The first, and most common, method is simple retrieval. As it's name
 147     implies simple retrieval allows you to simply to provide the column =>
 148     value pairs that should be used to locate the user in question. An
 149     example of this usage is below:
 150
 151         if ($c->authenticate({
 152                               username => $c->req->params->{'username'},
 153                               password => $c->req->params->{'password'},
 154                               status => [ 'registered', 'active', 'loggedin']
 155                              })) {
 156
 157             # ... authenticated user code here
 158         }
 159
 160     The above example would attempt to retrieve a user whose username column
 161     matched the username provided, and whose status column matched one of
 162     the values provided. These name => value pairs are used more or less
 163     directly in the DBIx::Class' search() routine, so in most cases, you can
 164     use DBIx::Class syntax to retrieve the user according to whatever rules
 165     you have.
 166
 167     NOTE: Because the password in most cases is encrypted - it is not used
 168     directly but it's encryption and comparison with the value provided is
 169     usually handled by the Password Credential. Part of the Password
 170     Credential's behavior is to remove the password argument from the
 171     authinfo that is passed to the storage module. See
 172     Catalyst::Plugin::Authentication::Credential::Password.
 173
 174     One thing you need to know about this retrieval method is that the name
 175     portion of the pair is checked against the user class' column list.
 176     Pairs are only used if a matching column is found. Other pairs will be
 177     ignored. This means that you can only provide simple name-value pairs,
 178     and that some more advanced DBIx::Class constructs, such as '-or',
 179     '-and', etc. are in most cases not possible using this method. For
 180     queries that require this level of functionality, see the 'searchargs'
 181     method below.
 182
 183   Advanced Retrieval
 184     The Searchargs and Resultset retrieval methods are used when more
 185     advanced features of the underlying DBIx::Class schema are required.
 186     These methods provide a direct interface with the DBIx::Class schema and
 187     therefore require a better understanding of the DBIx::Class module.
 188
 189    The dbix_class key
 190     Since the format of these arguments are often complex, they are not keys
 191     in the base authinfo hash. Instead, both of these arguments are placed
 192     within a hash attached to the store-specific 'dbix_class' key in the
 193     base $authinfo hash. When the DBIx::Class authentication store sees the
 194     'dbix_class' key in the passed authinfo hash, all the other information
 195     in the authinfo hash is ignored and only the values within the
 196     'dbix_class' hash are used as though they were passed directly within
 197     the authinfo hash. In other words, if 'dbix_class' is present, it
 198     replaces the authinfo hash for processing purposes.
 199
 200     The 'dbix_class' hash can be used to directly pass arguments to the
 201     DBIx::Class authentication store. Reasons to do this are to avoid
 202     credential modification of the authinfo hash, or to avoid overlap
 203     between credential and store key names. It's a good idea to avoid using
 204     it in this way unless you are sure you have an overlap/modification
 205     issue. However, the two advanced retrieval methods, searchargs and
 206     resultset, require it's use, as they are only processed as part of the
 207     'dbix_class' hash
 208
 209     Searchargs
 210         The searchargs method of retrieval allows you to specify an arrayref
 211         containing the two arguments to the search() method from
 212         DBIx::Class::ResultSet. If provided, all other args are ignored, and
 213         the search args provided are used directly to locate the user. An
 214         example will probably make more sense:
 215
 216             if ($c->authenticate(
 217                 {
 218                     password => $password,
 219                     'dbix_class' =>
 220                         {
 221                             searchargs = [ { -or => [ username => $username,
 222                                                       email => $email,
 223                                                       clientid => $clientid ]
 224                                            },
 225                                            { prefetch => qw/ preferences / }
 226                                          ]
 227                         }
 228                 } ) )
 229             {
 230                 # do successful authentication actions here.
 231             }
 232
 233         The above would allow authentication based on any of the three items
 234         - username, email or clientid and would prefetch the data related to
 235         that user from the preferences table. The searchargs array is passed
 236         directly to the search() method associated with the user_class.
 237
 238     Resultset
 239         The resultset method of retrieval allows you to directly specify a
 240         resultset to be used for user retrieval. This allows you to create a
 241         resultset within your login action and use it for retrieving the
 242         user. A simple example:
 243
 244             my $rs = $c->model('MyApp::User')->search({ email => $c->request->params->{'email'} });
 245                ... # further $rs adjustments
 246
 247             if ($c->authenticate({
 248                                    password => $password,
 249                                    'dbix_class' => {  resultset = $rs }
 250                                  })) {
 251                # do successful authentication actions here.
 252             }
 253
 254         Be aware that the resultset method will not verify that you are
 255         passing a resultset that is attached to the same user_class as
 256         specified in the config.
 257
 258         NOTE: All of these methods of user retrieval, including the
 259         resultset method, consider the first row returned to be the matching
 260         user. In most cases there will be only one matching row, but it is
 261         easy to produce multiple rows, especially when using the advanced
 262         retrieval methods. Remember, what you get when you use this module
 263         is what you would get when calling search(...)->first;
 264
 265         NOTE ALSO: The user info used to save the user to the session and to
 266         retrieve it is the same regardless of what method of retrieval was
 267         used. In short, the value in the id field (see 'id_field' config
 268         item) is used to retrieve the user from the database upon restoring
 269         from the session. When the DBIx::Class storage module does this, it
 270         does so by doing a simple search using the id field. In other words,
 271         it will not use the same arguments you used to request the user
 272         initially. This is especially important to those using the advanced
 273         methods of user retrieval. If you need more complicated logic when
 274         reviving the user from the session, you will most likely want to
 275         subclass the
 276         Catalyst::Plugin::Authentication::Store::DBIx::Class::User class and
 277         provide your own for_session and from_session routines.
 278
 279 METHODS
 280     There are no publicly exported routines in the DBIx::Class
 281     authentication store (or indeed in most authentication stores) However,
 282     below is a description of the routines required by
 283     Catalyst::Plugin::Authentication for all authentication stores. Please
 284     see the documentation for Catalyst::Plugin::Authentication::Internals
 285     for more information.
 286
 287     new ( $config, $app )
 288         Constructs a new store object.
 289
 290     find_user ( $authinfo, $c )
 291         Finds a user using the information provided in the $authinfo hashref
 292         and returns the user, or undef on failure; This is usually called
 293         from the Credential. This translates directly to a call to
 294         Catalyst::Plugin::Authentication::Store::DBIx::Class::User's load()
 295         method.
 296
 297     for_session ( $c, $user )
 298         Prepares a user to be stored in the session. Currently returns the
 299         value of the user's id field - (as indicated by the 'id_field'
 300         config element)
 301
 302     from_session ( $c, $frozenuser)
 303         Revives a user from the session based on the info provided in
 304         $frozenuser. Currently treats $frozenuser as an id and retrieves a
 305         user with a matching id.
 306
 307     user_supports
 308         Provides information about what the user object supports.
 309
 310 NOTES
 311     As of the current release, session storage consists of simply storing
 312     the user's id in the session, and then using that same id to re-retrieve
 313     the users information from the database upon restoration from the
 314     session. More dynamic storage of user information in the session is
 315     intended for a future release.
 316
 317 BUGS AND LIMITATIONS
 318     None known currently, please email the author if you find any.
 319
 320 SEE ALSO
 321     Catalyst::Plugin::Authentication,
 322     Catalyst::Plugin::Authentication::Internals, and
 323     Catalyst::Plugin::Authorization::Roles
 324
 325 AUTHOR
 326     Jason Kuri (jayk@cpan.org)
 327
 328 LICENSE
 329     Copyright (c) 2007 the aforementioned authors. All rights reserved. This
 330     program is free software; you can redistribute it and/or modify it under
 331     the same terms as Perl itself.
 332