Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       Catalyst::Authentication::Store::DBIx::Class - A	storage	class for
       Catalyst	Authentication using DBIx::Class

       This documentation refers to version 0.1506.

	   use Catalyst	qw/

	   __PACKAGE__->config('Plugin::Authentication'	=> {
	       default_realm =>	'members',
	       realms => {
		   members => {
		       credential => {
			   class => 'Password',
			   password_field => 'password',
			   password_type => 'clear'
		       store =>	{
			   class => 'DBIx::Class',
			   user_model => 'MyApp::User',
			   role_relation => 'roles',
			   role_field => 'rolename',

	   # Log a user	in:

	   sub login : Global {
	       my ( $self, $ctx	) = @_;

				 screen_name =>	$ctx->req->params->{username},
				 password => $ctx->req->params->{password},
				 status	=> [ 'registered', 'loggedin', 'active']

	   # verify a role

	   if (	$ctx->check_user_roles(	'editor' ) ) {
	       # do editor stuff

       The Catalyst::Authentication::Store::DBIx::Class	class provides access
       to authentication information stored in a database via DBIx::Class.

       The DBIx::Class authentication store is activated by setting the	store
       config's	class element to DBIx::Class as	shown above. See the
       Catalyst::Plugin::Authentication	documentation for more details on
       configuring the store. You can also use
       Catalyst::Authentication::Realm::SimpleDB for a simplified setup.

       The DBIx::Class storage module has several configuration	options

	   __PACKAGE__->config('Plugin::Authentication'	=> {
	       default_realm =>	'members',
	       realms => {
		   members => {
		       credential => {
			   # ...
		       store =>	{
			   class => 'DBIx::Class',
			   user_model => 'MyApp::User',
			   role_relation => 'roles',
			   role_field => 'rolename',
			   ignore_fields_in_find => [ 'remote_name' ],
			   use_userdata_from_session =>	1,

	   Class is part of the	core Catalyst::Plugin::Authentication module;
	   it contains the class name of the store to be used.

	   Contains the	model name (as passed to "$ctx->model()") of the
	   DBIx::Class schema to use as	the source for user information. This
	   config item is REQUIRED.

	   (Note that this option used to be called "user_class". "user_class"
	   is still functional,	but should be used only	for compatibility with
	   previous configs.  The setting called "user_class" on other
	   authentication stores is present, but named "store_user_class" in
	   this	store)

	   If your role	information is stored in the same table	as the rest of
	   your	user information, this item tells the module which field
	   contains your role information.  The	DBIx::Class authentication
	   store expects the data in this field	to be a	series of role names
	   separated by	some combination of spaces, commas, or pipe

	   If your role	information is stored in a separate table, this	is the
	   name	of the relation	that will lead to the roles the	user is	in.
	   If this is specified, then a	role_field is also required.  Also
	   when	using this method it is	expected that your role	table will
	   return one row for each role	the user is in.

	   This	is the name of the field in the	role table that	contains the
	   string identifying the role.

	   This	item is	an array containing fields that	may be passed to the
	   "$ctx->authenticate()" routine (and therefore find_user in the
	   storage class), but which should be ignored when creating the
	   DBIx::Class search to retrieve a user. This makes it	possible to
	   avoid problems when a credential requires an	authinfo element whose
	   name	overlaps with a	column name in your users table.  If this
	   doesn't make	sense to you, you probably don't need it.

	   Under normal	circumstances, on each request the user's data is re-
	   retrieved from the database using the primary key for the user
	   table.  When	this flag is set in the	configuration, it causes the
	   DBIx::Class store to	avoid this database hit	on session restore.
	   Instead, the	user object's column data is retrieved from the
	   session and used as-is.

	   NOTE: Since the user	object's column	data is	only stored in the
	   session during the initial authentication of	the user, turning this
	   on can potentially lead to a	situation where	the data in
	   "$ctx->user"	is different from what is stored the database.	You
	   can force a reload of the data from the database at any time	by
	   calling "$ctx->user->get_object(1);"	Note that this will update
	   "$ctx->user"	for the	remainder of this request.  It will NOT	update
	   the session.	 If you	need to	update the session you should call
	   "$ctx->update_user_in_session()" as well.

	   This	allows you to override the authentication user class that the
	   DBIx::Class store module uses to perform its	work.  Most of the
	   work	done in	this module is actually	done by	the user class,
	   Catalyst::Authentication::Store::DBIx::Class::User, so overriding
	   this	doesn't	make much sense	unless you are using your own class to
	   extend the functionality of the existing class.  Chances are	you do
	   not want to set this.

	   In most cases, this config variable does not	need to	be set,	as
	   Catalyst::Authentication::Store::DBIx::Class	will determine the
	   primary key of the user table on its	own.  If you need to override
	   the default,	or your	user table has multiple	primary	keys, then
	   id_field should contain the column name that	should be used to
	   restore the user.  A	given value in this column should correspond
	   to a	single user in the database.  Note that	this is	used ONLY when
	   restoring a user from the session and has no	bearing	whatsoever in
	   the initial authentication process.	Note also that if
	   use_userdata_from_session is	enabled, this config parameter is not
	   used	at all.

       The Catalyst::Authentication::Store::DBIx::Class	storage	module is not
       called directly from application	code.  You interface with it through
       the $ctx->authenticate()	call.

       There are three methods you can use to retrieve information from	the
       DBIx::Class storage module.  They are Simple retrieval, and the
       advanced	retrieval methods Searchargs and Resultset.

   Simple Retrieval
       The first, and most common, method is simple retrieval. As its name
       implies simple retrieval	allows you to simply to	provide	the column =>
       value pairs that	should be used to locate the user in question. An
       example of this usage is	below:

	   if ($ctx->authenticate({
				 screen_name =>	$ctx->req->params->{'username'},
				 password => $ctx->req->params->{'password'},
				 status	=> [ 'registered', 'active', 'loggedin']
				})) {

	       # ... authenticated user	code here

       The above example would attempt to retrieve a user whose	username
       column (here, screen_name) matched the username provided, and whose
       status column matched one of the	values provided. These name => value
       pairs are used more or less directly in the DBIx::Class search()
       routine,	so in most cases, you can use DBIx::Class syntax to retrieve
       the user	according to whatever rules you	have.

       NOTE: Because the password in most cases	is encrypted - it is not used
       directly	but its	encryption and comparison with the value provided is
       usually handled by the Password Credential. Part	of the Password
       Credential's behavior is	to remove the password argument	from the
       authinfo	that is	passed to the storage module. See

       One thing you need to know about	this retrieval method is that the name
       portion of the pair is checked against the user class's column list.
       Pairs are only used if a	matching column	is found. Other	pairs will be
       ignored.	This means that	you can	only provide simple name-value pairs,
       and that	some more advanced DBIx::Class constructs, such	as '-or',
       '-and', etc. are	in most	cases not possible using this method. For
       queries that require this level of functionality, see the 'searchargs'
       method below.

   Advanced Retrieval
       The Searchargs and Resultset retrieval methods are used when more
       advanced	features of the	underlying DBIx::Class schema are required.
       These methods provide a direct interface	with the DBIx::Class schema
       and therefore require a better understanding of the DBIx::Class module.

       The dbix_class key

       Since the format	of these arguments are often complex, they are not
       keys in the base	authinfo hash.	Instead, both of these arguments are
       placed within a hash attached to	the store-specific 'dbix_class'	key in
       the base	$authinfo hash.	 When the DBIx::Class authentication store
       sees the	'dbix_class' key in the	passed authinfo	hash, all the other
       information in the authinfo hash	is ignored and only the	values within
       the 'dbix_class'	hash are used as though	they were passed directly
       within the authinfo hash.  In other words, if 'dbix_class' is present,
       it replaces the authinfo	hash for processing purposes.

       The 'dbix_class'	hash can be used to directly pass arguments to the
       DBIx::Class authentication store. Reasons to do this are	to avoid
       credential modification of the authinfo hash, or	to avoid overlap
       between credential and store key	names. It's a good idea	to avoid using
       it in this way unless you are sure you have an overlap/modification
       issue. However, the two advanced	retrieval methods, searchargs, result
       and resultset, require its use, as they are only	processed as part of
       the 'dbix_class'	hash.

	   The searchargs method of retrieval allows you to specify an
	   arrayref containing the two arguments to the	search() method	from
	   DBIx::Class::ResultSet.  If provided, all other args	are ignored,
	   and the search args provided	are used directly to locate the	user.
	   An example will probably make more sense:

	       if ($ctx->authenticate(
		       password	=> $password,
		       'dbix_class' =>
			       searchargs => [ { -or =>	[ username => $username,
							 email => $email,
							 clientid => $clientid ]
					      {	prefetch => qw/	preferences / }
		   } ) )
		   # do	successful authentication actions here.

	   The above would allow authentication	based on any of	the three
	   items - username, email, or clientid	- and would prefetch the data
	   related to that user	from the preferences table. The	searchargs
	   array is passed directly to the search() method associated with the

	   The result method of	retrieval allows you to	look up	the user
	   yourself and	pass on	the loaded user	to the authentication store.

	       my $user	= $ctx->model('MyApp::User')->find({ ... });

	       if ($ctx->authenticate({	dbix_class => {	result => $user	} })) {

	   Be aware that the result method will	not verify that	you are
	   passing a result that is attached to	the same user_model as
	   specified in	the config or even loaded from the database, as
	   opposed to existing only in memory. It's your responsibility	to
	   make	sure of	that.

	   The resultset method	of retrieval allows you	to directly specify a
	   resultset to	be used	for user retrieval. This allows	you to create
	   a resultset within your login action	and use	it for retrieving the
	   user. A simple example:

	       my $rs =	$ctx->model('MyApp::User')->search({ email => $ctx->request->params->{'email'} });
		  ... #	further	$rs adjustments

	       if ($ctx->authenticate({
				      password => $password,
				      'dbix_class' => {	resultset => $rs }
				    }))	{
		  # do successful authentication actions here.

	   Be aware that the resultset method will not verify that you are
	   passing a resultset that is attached	to the same user_model as
	   specified in	the config.

	   NOTE: The resultset and searchargs methods of user retrieval,
	   consider the	first row returned to be the matching user. In most
	   cases there will be only one	matching row, but it is	easy to
	   produce multiple rows, especially when using	the advanced retrieval
	   methods. Remember, what you get when	you use	this module is what
	   you would get when calling search(...)->first;

	   NOTE	ALSO:  The user	info used to save the user to the session and
	   to retrieve it is the same regardless of what method	of retrieval
	   was used.  In short,	the value in the id field (see 'id_field'
	   config item)	is used	to retrieve the	user from the database upon
	   restoring from the session.	When the DBIx::Class storage module
	   does	this, it does so by doing a simple search using	the id field.
	   In other words, it will not use the same arguments you used to
	   request the user initially.	This is	especially important to	those
	   using the advanced methods of user retrieval.  If you need more
	   complicated logic when reviving the user from the session, you will
	   most	likely want to subclass	the
	   Catalyst::Authentication::Store::DBIx::Class::User class and
	   provide your	own for_session	and from_session routines.

       There are no publicly exported routines in the DBIx::Class
       authentication store (or	indeed in most authentication stores).
       However,	below is a description of the routines required	by
       Catalyst::Plugin::Authentication	for all	authentication stores.	Please
       see the documentation for Catalyst::Plugin::Authentication::Internals
       for more	information.

   new ( $config, $app )
       Constructs a new	store object.

   find_user ( $authinfo, $c )
       Finds a user using the information provided in the $authinfo hashref
       and returns the user, or	undef on failure. This is usually called from
       the Credential. This translates directly	to a call to
       Catalyst::Authentication::Store::DBIx::Class::User's load() method.

   for_session ( $c, $user )
       Prepares	a user to be stored in the session. Currently returns the
       value of	the user's id field (as	indicated by the 'id_field' config

   from_session	( $c, $frozenuser)
       Revives a user from the session based on	the info provided in
       $frozenuser.  Currently treats $frozenuser as an	id and retrieves a
       user with a matching id.

       Provides	information about what the user	object supports.

   auto_update_user( $authinfo,	$c, $res )
       This method is called if	the realm's auto_update_user setting is	true.
       It will delegate	to the user object's "auto_update" method.

   auto_create_user( $authinfo,	$c )
       This method is called if	the realm's auto_create_user setting is	true.
       It will delegate	to the user class's (resultset)	"auto_create" method.

       As of the current release, session storage consists of simply storing
       the user's id in	the session, and then using that same id to re-
       retrieve	the user's information from the	database upon restoration from
       the session.  More dynamic storage of user information in the session
       is intended for a future	release.

       None known currently; please email the author if	you find any.

       Catalyst::Plugin::Authentication::Internals, and

       Jason Kuri (

       Copyright (c) 2007 the aforementioned authors. All rights reserved.
       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.24.1		       Catalyst::Authentication::Store::DBIx::Class(3)


Want to link to this manual page? Use this URL:

home | help