|new( $config, $app, $realm )||
The new() method is called only once, during the setup process of
first argument, $config, is a hash reference containing the configuration
information for the store module. The second argument is a reference to the
Note that when new() is called, Catalyst has not yet loaded the various controller and model classes, nor is it definite that other plugins have been loaded, so your new() method must not rely on any of those being present. If any of this is required for your store to function, you should defer that part of initialization until the first method call.
The new() method should return a blessed reference to your store object.
|find_user( $authinfo, $c )||
This is the workhorse of any authentication store. Its job is to take the
information provided to it via the $authinfo hashref and locate the user
that matches it. It should return a reference to a user object. A return value
of anything else is considered to mean no user was found that matched the
How find_user() accomplishes its job is entirely up to you, the author, as is what $authinfo is required to contain. Many stores will simply use a username element in $authinfo to locate the user, but more advanced functionality is possible and you may bend the $authinfo to your needs. Be aware, however, that both Credentials and Stores usually work with the same $authinfo hash, so take care to avoid overlapping element names.
Please note that this routine may be called numerous times in various circumstances, and that a successful match for a user here does <B>NOTB> necessarily constitute successful authentication. Your store class should never assume this and in most cases $c <B>should not be modifiedB> by your store object.
|for_session( $c, $user )||This method is responsible for preparing a user object for storage in the session. It should return information that can be placed in the session and later used to restore a user object (using the from_session() method). It should therefore ensure that whatever information provided can be used by the from_session() method to locate the unique user being saved. Note that there is no guarantee that the same Catalyst instance will receive both the for_session() and from_session() calls. You should take care to provide information that can be used to restore a user, regardless of the current state of the application. A good rule of thumb is that if from_session() can revive the user with the given information even if the Catalyst application has just started up, you are in good shape.|
|from_session( $c, $frozenuser )||This method is called whenever a user is being restored from the session. $frozenuser contains the information that was stored in the session for the user. This will under normal circumstances be the exact data your store returned from the previous call to for_session(). from_session() should return a valid user object.|
|user_supports( $feature, ... )||This method allows credentials and other objects to inquire as to what the underlying user object is capable of. This is pretty-well free-form and the main purpose is to allow graceful integration with credentials and applications that may provide advanced functionality based on whether the underlying user object can do certain things. In most cases you will want to pass this directly to the underlying user class supports method. Note that this is used as a <B>classB> method against the user class and therefore must be able to function without an instantiated user object.|
If you want your store to be able to auto- create users, then you can implement these methods:
auto_update_user( $authinfo, $c, $res )
auto_create_user( $authinfo, $c )
The user object is an important piece of your store module. It will be the part of the system that the application developer will interact with most. As such, the API for the user object is very rigid. All user objects <B>MUSTB> inherit from Catalyst::Authentication::User.
The routines required by the Catalyst::Plugin::Authentication plugin are below. Note that of these, only get_object is strictly required, as the Catalyst::Authentication::User base class contains reasonable implementations of the rest. If you do choose to implement only the get_object() routine, please read the base class code and documentation so that you fully understand how the other routines will be implemented for you.
Also, your user object can implement whatever additional methods you require to provide the functionality you need. So long as the below are implemented, and you dont overlap the base class methods with incompatible routines, you should experience no problems.
id( ) The id() method should return a unique id (scalar) that can be used to retreive this user from the store. Often this will be provided to the stores find_user() routine as id => $user->id so you should ensure that your stores find_user() can cope with that. supports( $feature, $subfeature ... ) This method checks to see if the user class supports a particular feature. It is implemented such that each argument provides a subfeature of the previous argument. In other words, passing foo, bar would return true if the user supported the foo feature, and the bar feature of foo. This is implemented in Catalyst::Authentication::User, so if your class inherits from that, you do not need to implement this and can instead implement supported_features(). supported_features( ) This method should return a hashref of features supported by the user class. This is for more flexible integration with some Credentials / applications. It is not required that you support anything, and returning undef is perfectly acceptable and in most cases what you will do. get( $fieldname ) This method should return the value of the field matching fieldname provided, or undef if there is no field matching that fieldname. In most cases this will access the underlying storage mechanism for the user data and return the information. This is used as a standard method of accessing an authenticated users data, and MUST be implemented by all user objects.
<B>NoteB>: There is no equivalent set method. Each user class is likely to vary greatly in how data must be saved and it is therefore impractical to try to provide a standard way of accomplishing it. When an application developer needs to save data, they should obtain the underlying object / data by calling get_object, and work with it directly.
get_object( ) This method returns the underlying user object. If your user object is backed by another object class, this method should return that underlying object. This allows the application developer to obtain an editable object. Generally speaking this will only be done by developers who know what they are doing and require advanced functionality which is either unforeseen or inconsistent across user classes. If your object is not backed by another class, or you need to provide additional intermediate functionality, it is perfectly reasonable to return $self.
Compared to writing a store, writing a credential is very simple. There is only one class to implement, and it consists of only two required routines. They are:
new() - instantiates the credential object authenticate() - performs the authentication and returns a user object
new( $config, $app, $realm ) Like the Store method of the same name, the new() method is called only once, during the setup process of Catalyst::Plugin::Authentication. The first argument, $config, is a hash reference containing the configuration information for the credential module. The second argument is a reference to the Catalyst application. $realm is the instantiated Realm object, which you may use to access realm routines - such as find_user.
Again, when the credentials new() method is called, Catalyst has not yet loaded the various controller and model classes.
The new method should perform any necessary setup required and instantiate your credential object. It should return your instantiated credential.
authenticate( $c, $realm, $authinfo ) This is the workhorse of your credential. When $c->authenticate() is called the Catalyst::Plugin::Authentication module retrieves the realm object and passes it, along with the $authinfo hash to your credentials authenticate method. Your module should use the $authinfo hash to obtain the user from the realm passed, and then perform any credential verification steps necessary to authenticate the user. This method should return the user object returned by the authentication store if credential verification succeeded. It should return undef on failure.
How your credential module performs the credential verification is entirely up to you. In most cases, the credential will retrieve a user from the store first (using the stores find_user() method), and then validate the users information. However, this does not have to be the case.
It is perfectly acceptable for your credential to perform other tasks prior to attempting to retrieve the user from the store. It may also make sense for your credential to perform activities which help to locate the user in question, for example, finding a user id based on an encrypted token. In these scenarios, the $authinfo hash passed to find_user() can be different than that which is passed in to $c->authenticate(). Once again this is perfectly acceptable if it makes sense for your credential, though you are strongly advised to note this behavior clearly in your credentials documentation - as application authors are almost certainly expecting the user to be found using the information provided to $c->authenticate().
Look at the Catalyst::Authentication::Credential::Password module source to see this in action. In order to avoid possible mismatches between the encrypted and unencrypted passwords, the password credential actually removes the provided password from the authinfo array. It does this because, in many cases, the stores password field will be encrypted in some way, and the password passed to $c->authenticate is almost certainly in plaintext.
NOTE: You should always assume that a store is going to use all the information passed to it to locate the user in question. If there are fields in the $authinfo hash that you are sure are specific to your credential, you may want to consider removing them before user retrieval. A better solution is to place those arguments that are specific to your credential within their own subhash named after your module.
The Catalyst::Authentication::Store::DBIx::Class module does this in order to encapsulate arguments intended specifically for that module. See the Catalyst::Authentication::Store::DBIx::Class::User source for details.
Jay Kuri, email@example.com
Copyright (c) 2005 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.20.3||CATALYST::PLUGIN::AUTHENTICATION::INTERNALS (3)||2012-06-30|