Trim trailing whitespace.

[catagits/Catalyst-Authentication-Realm-Adaptor.git] / README

Catalyst::Authenticatio\bUn\bs:\be:\brRe\bCa\bol\bnm\bt:\br:\biA\bbd\bua\bt\bCp\be\bat\bd\bto\bar\bP\bl(\be\by3\br\bs)\bl\bt:D\b:o\bAc\buu\btm\bhe\ben\bnt\bta\bit\bci\bao\btn\bion::Realm::Adaptor(3)



N\bNA\bAM\bME\bE
       Catalyst::Authentication::Realm::Adaptor − Adjust parameters of authen‐
       tication processes on the fly

V\bVE\bER\bRS\bSI\bIO\bON\bN
       Version 0.01

S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
       The Catalyst::Authentication::Realm::Adaptor allows for modification of
       authentication parameters within the catalyst application. It’s basi‐
       cally a filter used to adjust authentication parameters globally within
       the application or to adjust user retrieval parameters provided by the
       credential in order to be compatible with a different store. It pro‐
       vides for better control over interaction between credentials and
       stores. This is particularly useful when working with external authen‐
       tication such as OpenID or OAuth.

        __PACKAGE__‐>config(
           ’Plugin::Authentication’ => {
                   ’default’ => {
                       class => ’Adaptor’
                       credential => {
                           class => ’Password’,
                           password_field => ’secret’,
                           password_type  => ’hashed’,
                           password_hash_type => ’SHA‐1’,
                       },
                       store => {
                           class      => ’DBIx::Class’,
                           user_class => ’Schema::Person’,
                       },
                       store_adaptor => {
                           method => ’merge_hash’,
                           merge_hash => {
                               status => [ ’temporary’, ’active’ ]
                           }
                       }
                   },
               }
           }
        );

       The above example ensures that no matter how $c−>_\ba_\bu_\bt_\bh_\be_\bn_\bt_\bi_\bc_\ba_\bt_\be_\b(_\b) is
       called within your application, the key ’status’ is added to the
       authentication hash.  This allows you to, among other things, set
       parameters that should always be applied to your authentication process
       or modify the parameters to better connect a credential and a store
       that were not built to work together. In the above example, we are mak‐
       ing sure that the user search is restricted to those with a status of
       either ’temporary’ or ’active.’

       This realm works by intercepting the original authentication informa‐
       tion between the time "$c−>authenticate($authinfo)" is called and the
       time the realm’s "$realm−>authenticate($c,$authinfo)" method is called,
       allowing for the $authinfo parameter to be modified or replaced as your
       application requires. It can also operate after the call to the creden‐
       tial’s "authenticate()" method but before the call to the store’s
       "find_user" method.

       If you don’t know what the above means, you probably do not need this
       module.

C\bCO\bON\bNF\bFI\bIG\bGU\bUR\bRA\bAT\bTI\bIO\bON\bN
       The configuration for this module goes within your realm configuration
       alongside your credential and store options.

       This module can operate in two points during authentication processing.
       The first is prior the realm’s "authenticate" call (immediately after
       the call to "$c−>authenticate()".) To operate here, your filter options
       should go in a hash under the key "credential_adaptor".

       The second point is after the call to credential’s "authenticate"
       method but immediately before the call to the user store’s "find_user"
       method. To operate prior to "find_user", your filter options should go
       in a hash under the key "store_adaptor".

       The filtering options for both points are the same, and both the
       "store_adaptor" and "credential_adaptor" can be used simultaneously in
       a single realm.

       m\bme\bet\bth\bho\bod\bd

       There are four ways to configure your filters.  You specify which one
       you want by setting the "method" configuration option to one of the
       following: "merge_hash", "new_hash", "code", or "action".  You then
       provide the additional information based on which method you have cho‐
       sen.  The different options are described below.

       merge_hash
                credential_adaptor => {
                    method => ’merge_hash’,
                    merge_hash => {
                        status => [ ’temporary’, ’active’ ]
                    }
                }

               This causes the original authinfo hash to be merged with a hash
               provided by the realm configuration under the key "merge_hash"
               key. This is a deep merge and in the case of a conflict, the
               hash specified by merge_hash takes precedence over what was
               passed into the authenticate or find_user call. The method of
               merging is described in detail in the "HASH MERGING" section
               below.

       new_hash
                store_adaptor => {
                    method => ’new_hash’,
                    new_hash => {
                        username => ’+(user)’,  # this sets username to the value of $originalhash{user}
                        user_source => ’openid’
                    }
                }

               This causes the original authinfo hash to be set aside and
               replaced with a new hash provided under the "new_hash" key. The
               new hash can grab portions of the original hash.  This can be
               used to remap the authinfo into a new format.  See the "HASH
               MERGING" section for information on how to do this.

       code
                store_adaptor => {
                    method => ’code’,
                    code => sub {
                        my ($realmname, $original_authinfo, $hashref_to_config ) = @_;
                        my $newauthinfo = {};
                        ## do something
                        return $newauthinfo;
                    }
                }

               The "code" method allows for more complex filtering by execut‐
               ing code provided as a subroutine reference in the "code" key.
               The realm name, original auth info and the portion of the con‐
               fig specific to this filter are passed as arguments to the pro‐
               vided subroutine. In the above example, it would be the entire
               store_adaptor hash. If you were using a code ref in a creden‐
               tial_adaptor, you’d get the credential_adapter config instead.

       action
                credential_adaptor => {
                    method => ’action’,
                    controller => ’UserProcessing’,
                    action => ’FilterCredentials’
                }

               The "action" method causes the adaptor to delegate filtering to
               a Catalyst action. This is similar to the code ref above,
               except that instead of simply calling the routine, the action
               specified is called via "<$c−"forward>>. The arguments passed
               to the action are the same as the code method as well, namely
               the realm name, the original authinfo hash and the config for
               the adaptor.

H\bHA\bAS\bSH\bH M\bME\bER\bRG\bGI\bIN\bNG\bG
       The hash merging mechanism in Catalyst::Authentication::Realm::Adaptor
       is not a simple merge of two hashes. It has some niceties which allow
       for both re‐mapping of existing keys, and a mechanism for removing keys
       from the original hash. When using the ’merge_hash’ method above, the
       keys from the original hash and the keys for the merge hash are simply
       combined with the merge_hash taking precedence in the case of a key
       conflict. If there are sub‐hashes they are merged as well.

       If both the source and merge hash contain an array for a given
       hash−key, the values in the merge array are appended to the original
       array.  Note that hashes within arrays will not be merged, and will
       instead simply be copied.

       Simple values are left intact, and in the case of a key existing in
       both hashes, the value from the merge_hash takes precedence. Note that
       in the case of a key conflict where the values are of different types,
       the value from the merge_hash will be used and no attempt is made to
       merge or otherwise convert them.

       A\bAd\bdv\bva\ban\bnc\bce\bed\bd m\bme\ber\brg\bgi\bin\bng\bg

       Whether you are using "merge_hash" or "new_hash" as the method, you
       have access to the values from the original authinfo hash.  In your new
       or merged hash, you can use values from anywhere within the original
       hash.  You do this by setting the value for the key you want to set to
       a special string indicating the key path in the original hash.  The
       string is formatted as follows: "<’+(key1.key2.key3)’">  This will grab
       the hash associated with key1, retrieve the hash associated with key2,
       and finally obtain the value associated with key3.  This is easier to
       show than to explain:

        my $originalhash = {
                               user => {
                                       details => {
                                           age       => 27,
                                           haircolor => ’black’,
                                           favoritenumbers => [ 17, 42, 19 ]
                                       }
                               }
                           };

         my $newhash = {
                           # would result in a value of ’black’
                           haircolor => ’+(user.details.haircolor)’,

                           # bestnumber would be 42.
                           bestnumber => ’+(user.details.favoritenumbers.1)’
                       }

       Given the example above, the value for the userage key would be 27,
       (obtained via "<’+(user.details.age)’">) and the value for bestnumber
       would be 42. Note that you can traverse both hashes and arrays using
       this method. This can be quite useful when you need the values that
       were passed in, but you need to put them under different keys.

       When using the "merge_hash" method, you sometimes may want to remove an
       item from the original hash. You can do this by providing a key in your
       merge_hash at the same point, but setting it’s value to ’−()’.  This
       will remove the key entirely from the resultant hash.  This works bet‐
       ter than simply setting the value to undef in some cases.

N\bNO\bOT\bTE\bES\bS a\ban\bnd\bd C\bCA\bAV\bVE\bEA\bAT\bTS\bS
       The authentication system for Catalyst is quite flexible.  In most
       cases this module is not needed.  Evidence of this fact is that the
       Catalyst auth system was substantially unchanged for 2+ years prior to
       this modules first release.  If you are looking at this module, then
       there is a good chance your problem would be better solved by adjusting
       your credential or store directly.

       That said, there are some areas where this module can be particularly
       useful.  For example, this module allows for global application of
       additional arguments to authinfo for a certain realm via your config.
       It also allows for preliminary testing of alternate configs before you
       adjust every "$c−>authenticate()" call within your application.

       It is also useful when combined with the various external authentica‐
       tion modules available, such as OpenID, OAuth or Facebook. These mod‐
       ules expect to store their user information in the Hash provided by the
       Minimal user store.  Often, however, you want to store user information
       locally in a database or other storage mechanism. Doing this lies some‐
       where between difficult and impossible normally. With the Adapter
       realm, you can massage the authinfo hash between the credential’s veri‐
       fication and the creation of the local user, and instead use the infor‐
       mation returned to look up a user instead.

       Using the external auth mechanisms and the "action" method, you can
       actually trigger an action to create a user record on the fly when the
       user has authenticated via an external method.  These are just some of
       the possibilities that Adaptor provides that would otherwise be very
       difficult to accomplish, even with Catalyst’s flexible authentication
       system.

       With all of that said, caution is warranted when using this module.  It
       modifies the behavior of the application in ways that are not obvious
       and can therefore lead to extremely hard to track‐down bugs.  This is
       especially true when using the "action" filter method.  When a devel‐
       oper calls "$c−>authenticate()" they are not expecting any actions to
       be called before it returns.

       If you use the "action" method, I strongly recommend that you use it
       only as a filter routine and do not do other catalyst dispatch related
       activities (such as further forwards, detach’s or redirects).  Also
       note that it is E\bEX\bXT\bTR\bRE\bEM\bME\bEL\bLY\bY D\bDA\bAN\bNG\bGE\bER\bRO\bOU\bUS\bS to call authentication routines
       from within a filter action.  It is extremely easy to accidentally cre‐
       ate an infinite recursion bug which can crash your Application.  In
       short − D\bDO\bON\bN’\b’T\bT D\bDO\bO I\bIT\bT.

A\bAU\bUT\bTH\bHO\bOR\bR
       Jay Kuri, "<jayk at cpan.org>"

B\bBU\bUG\bGS\bS
       Please report any bugs or feature requests to "bug−catalyst−authentica‐
       tion−realm−adaptor at rt.cpan.org", or through the web interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst−Authentica‐
       tion−Realm−Adaptor>.  I will be notified, and then you’ll automatically
       be notified of progress on your bug as I make changes.

S\bSU\bUP\bPP\bPO\bOR\bRT\bT
       You can find documentation for this module with the perldoc command.

           perldoc Catalyst::Authentication::Realm::Adaptor

       You can also look for information at:

       * Search CPAN
           <http://search.cpan.org/dist/Catalyst−Authentication−Realm−Adap‐
           tor/>

       * Catalyzed.org Wiki
           <http://wiki.catalyzed.org/cpan−modules/Catalyst−Authentica‐
           tion−Realm−Adaptor>

A\bAC\bCK\bKN\bNO\bOW\bWL\bLE\bED\bDG\bGE\bEM\bME\bEN\bNT\bTS\bS
C\bCO\bOP\bPY\bYR\bRI\bIG\bGH\bHT\bT &\b& L\bLI\bIC\bCE\bEN\bNS\bSE\bE
       Copyright 2009 Jay Kuri, 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.8.9                       20\bC0\ba9\bt‐\ba0\bl7\by‐\bs2\bt6\b::Authentication::Realm::Adaptor(3)