+++ /dev/null
-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)
projects / catagits/Catalyst-Authentication-Realm-Adaptor.git / commitdiff