-Catalyst-Authentication-Realm-Adaptor
+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)
-The README is used to introduce the module and provide instructions on
-how to install the module, any machine dependencies it may have (for
-example C compilers and installed libraries) and any other information
-that should be provided before the module is installed.
-A README file is required for CPAN modules since CPAN extracts the README
-file from a module distribution so that people browsing the archive
-can use it to get an idea of the module's uses. It is usually a good idea
-to provide version information here so that people can decide whether
-fixes for the module are worth downloading.
+N\bNA\bAM\bME\bE
+ Catalyst::Authentication::Realm::Adaptor − Adjust parameters of authen‐
+ tication processes on the fly
-INSTALLATION
+V\bVE\bER\bRS\bSI\bIO\bON\bN
+ Version 0.01
-To install this module, run the following commands:
+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.
- perl Makefile.PL
- make
- make test
- make install
+ __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’ ]
+ }
+ }
+ },
+ }
+ }
+ );
-SUPPORT AND DOCUMENTATION
+ 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.’
-After installing, you can find documentation for this module with the
-perldoc command.
+ 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.
- perldoc Catalyst::Authentication::Realm::Adaptor
+ If you don’t know what the above means, you probably do not need this
+ module.
-You can also look for information at:
+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.
- RT, CPAN's request tracker
- http://rt.cpan.org/NoAuth/Bugs.html?Dist=Catalyst-Authentication-Realm-Adaptor
+ 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".
- AnnoCPAN, Annotated CPAN documentation
- http://annocpan.org/dist/Catalyst-Authentication-Realm-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".
- CPAN Ratings
- http://cpanratings.perl.org/d/Catalyst-Authentication-Realm-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.
- Search CPAN
- http://search.cpan.org/dist/Catalyst-Authentication-Realm-Adaptor/
+ 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.
-COPYRIGHT AND LICENCE
+ merge_hash
+ credential_adaptor => {
+ method => ’merge_hash’,
+ merge_hash => {
+ status => [ ’temporary’, ’active’ ]
+ }
+ }
-Copyright (C) 2009 Jay Kuri
+ 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.
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
+ 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