From: Florian Ragwitz Date: Sun, 28 Mar 2010 21:52:27 +0000 (+0200) Subject: Remove README. It's generated. X-Git-Tag: 0.02~1 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Authentication-Realm-Adaptor.git;a=commitdiff_plain;h=99ccdc481a30d6c16955b5c58a0d7010b629261e Remove README. It's generated. --- diff --git a/Makefile.PL b/Makefile.PL index 542d99f..de08550 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -10,12 +10,12 @@ if( -e 'MANIFEST.SKIP' ) { system( 'pod2text lib/Catalyst/Authentication/Realm/Adaptor.pm > README'); } -requires ( +requires ( 'Catalyst::Runtime' => 0, 'Catalyst::Plugin::Authentication' => 0.10003, 'Moose' => 0, ); - + test_requires ('Test::More' => 0.42); -WriteAll; \ No newline at end of file +WriteAll; diff --git a/README b/README deleted file mode 100644 index d56a886..0000000 --- a/README +++ /dev/null @@ -1,300 +0,0 @@ -Catalyst::AuthenticatioUns:e:rReCaolnmt:r:iAbduatCpeatdtoarPl(ey3rs)lt:D:oAcuutmheennttaitciaotnion::Realm::Adaptor(3) - - - -NNAAMMEE - Catalyst::Authentication::Realm::Adaptor − Adjust parameters of authen‐ - tication processes on the fly - -VVEERRSSIIOONN - Version 0.01 - -SSYYNNOOPPSSIISS - 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−>_a_u_t_h_e_n_t_i_c_a_t_e_(_) 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. - -CCOONNFFIIGGUURRAATTIIOONN - 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. - - mmeetthhoodd - - 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. - -HHAASSHH MMEERRGGIINNGG - 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. - - AAddvvaanncceedd mmeerrggiinngg - - 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. - -NNOOTTEESS aanndd CCAAVVEEAATTSS - 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 EEXXTTRREEMMEELLYY DDAANNGGEERROOUUSS 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 − DDOONN’’TT DDOO IITT. - -AAUUTTHHOORR - Jay Kuri, "" - -BBUUGGSS - Please report any bugs or feature requests to "bug−catalyst−authentica‐ - tion−realm−adaptor at rt.cpan.org", or through the web interface at - . I will be notified, and then you’ll automatically - be notified of progress on your bug as I make changes. - -SSUUPPPPOORRTT - 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 - - - * Catalyzed.org Wiki - - -AACCKKNNOOWWLLEEDDGGEEMMEENNTTSS -CCOOPPYYRRIIGGHHTT && LLIICCEENNSSEE - 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 20C0a9t‐a0l7y‐s2t6::Authentication::Realm::Adaptor(3)