[catagits/Catalyst-Authentication-Store-DBIx-Class.git] / README

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

VERSION
    This documentation refers to version 0.02.

SYNOPSIS
        use Catalyst qw/
                        Authentication
                        Authorization::Roles/;

        __PACKAGE__->config->{authentication} = 
                        {  
                            default_realm => 'members',
                            realms => {
                                members => {
                                    credential => {
                                        class => 'Password',
                                        password_field => 'password',
                                        password_type => 'clear'
                                    },
                                    store => {
                                        class => 'DBIx::Class',
                                        user_class => 'MyApp::Users',
                                        id_field => 'user_id',
                                        role_relation => 'roles',
                                        role_field => 'rolename',                   
                                    }
                                }
                            }
                        };

        # Log a user in:
        
    sub login : Global {
            my ( $self, $c ) = @_;
            
        $c->authenticate({  
                              username => $c->req->params->username,
                              password => $c->req->params->password,
                              status => [ 'registered', 'loggedin', 'active']
                              }))
        }
        
    # verify a role 
        
    if ( $c->check_user_roles( 'editor' ) ) {
            # do editor stuff
        }

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

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

    The DBIx::Class storage module has several configuration options

        __PACKAGE__->config->{authentication} = 
                        {  
                            default_realm => 'members',
                            realms => {
                                members => {
                                    credential => {
                                        # ...
                                    },
                                    store => {
                                        class => 'DBIx::Class',
                                        user_class => 'MyApp::Users',
                                        id_field => 'user_id',
                                        role_relation => 'roles',
                                        role_field => 'rolename',
                                        ignore_fields_in_find => [ 'remote_name' ]          
                                    }
                                    }
                            }
                        };

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

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

    id_field
        Contains the field name containing the unique identifier for a user.
        This is used when storing and retrieving a user from the session.
        The value in this field should correspond to a single user in the
        database. Defaults to 'id'.

    role_column
        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 characters.

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

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

    ignore_fields_in_find
        This item is an array containing fields that may be passed to the
        $c->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.

    store_user_class
        This allows you to override the authentication user class that the
        DBIx::Class store module uses to perform it's work. Most of the work
        done in this module is actually done by the user class,
        Catalyst::Plugin::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.

USAGE
    The Catalyst::Plugin::Authentication::Store::DBIx::Class storage module
    is not called directly from application code. You interface with it
    through the $c->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 it's 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 ($c->authenticate({  
                              username => $c->req->params->{'username'},
                              password => $c->req->params->{'password'},
                              status => [ 'registered', 'active', 'loggedin']
                             })) {

            # ... authenticated user code here
        }

    The above example would attempt to retrieve a user whose username column
    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 it's 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
    Catalyst::Plugin::Authentication::Credential::Password.

    One thing you need to know about this retrieval method is that the name
    portion of the pair is checked against the user class' 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 and
    resultset, require it's use, as they are only processed as part of the
    'dbix_class' hash

    Searchargs
        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 ($c->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 user_class.

    Resultset
        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 = $c->model('MyApp::User')->search({ email => $c->request->params->{'email'} });
               ... # further $rs adjustments
               
    if ($c->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_class as
        specified in the config.

        NOTE: All of these methods of user retrieval, including the
        resultset method, 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::Plugin::Authentication::Store::DBIx::Class::User class and
        provide your own for_session and from_session routines.

METHODS
    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::Plugin::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 element)

    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.

    user_supports
        Provides information about what the user object supports.

NOTES
    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 users information from the database upon restoration from the
    session. More dynamic storage of user information in the session is
    intended for a future release.

BUGS AND LIMITATIONS
    None known currently, please email the author if you find any.

SEE ALSO
    Catalyst::Plugin::Authentication,
    Catalyst::Plugin::Authentication::Internals, and
    Catalyst::Plugin::Authorization::Roles

AUTHOR
    Jason Kuri (jayk@cpan.org)

LICENSE
    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.
Commit	Line	Data
b81ead77	1	NAME
	2	Catalyst::Plugin::Authentication::Store::DBIx::Class - A storage class
	3	for Catalyst Authentication using DBIx::Class
5000f545	4
b81ead77	5	VERSION
b81ead77	6	This documentation refers to version 0.02.
5000f545	7
b81ead77	8	SYNOPSIS
	9	use Catalyst qw/
	10	Authentication
	11	Authorization::Roles/;
5000f545	12
b81ead77	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	};
5000f545	33
b81ead77	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	}
5000f545	51
b81ead77	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.
5000f545	56
b81ead77	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.
5000f545	62
b81ead77	63	The DBIx::Class storage module has several configuration options
5000f545	64
b81ead77	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	};
5000f545	84
b81ead77	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.
5000f545	88
b81ead77	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.
5000f545	93
b81ead77	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'.
5000f545	99
b81ead77	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.
5000f545	106
b81ead77	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.
5000f545	113
b81ead77	114	role_field
	115	This is the name of the field in the role table that contains the
	116	string identifying the role.
5000f545	117
b81ead77	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.
5000f545	126
b81ead77	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
fbe76043	212	DBIx::Class::ResultSet. If provided, all other args are ignored, and
b81ead77	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.
5000f545	332