X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README;h=27a1d7478594a60750ee14eb9868b89c60cf8157;hb=4f4cf0f92aeb6acc5664cdcdee4a0d7a37348b39;hp=b8e6446af71f5c84f6631de6604641f738742c43;hpb=85db8ed74aeb58f5d76314702ba99034d7c0b09e;p=catagits%2FCatalyst-Authentication-Credential-OpenID.git diff --git a/README b/README index b8e6446..27a1d74 100644 --- a/README +++ b/README @@ -1,16 +1,386 @@ -Catalyst::Authentication::Credential::OpenID +NAME + Catalyst::Authentication::Credential::OpenID - OpenID credential for + Catalyst::Plugin::Authentication framework. -Just say "no" to document drift. See the POD for any details, -including copyright and licence, beyond installation. +VERSION + 0.14_05 +BACKWARDS COMPATIBILITY CHANGES + EXTENTION_ARGS v EXTENSIONS + NB: The extenstions were previously configured under the key + "extension_args". They are now configured under "extensions". This + prevents the need for double configuration but it breaks extensions in + your application if you do not change the name. The old version is + supported for now but may be phased out at any time. -INSTALLATION + As previously noted, "EXTENSIONS TO OPENID", I have not tested the + extensions. I would be grateful for any feedback or, better, tests. -To install this module, run the following commands: + FATALS + The problems encountered by failed OpenID operations have always been + fatals in the past. This is unexpected behavior for most users as it + differs from other credentials. Authentication errors here are no longer + fatal. Debug/error output is improved to offset the loss of information. + If for some reason you would prefer the legacy/fatal behavior, set the + configuration variable "errors_are_fatal" to a true value. - perl Makefile.PL - make - # See below for TEST_HTTP info - make test - make install +SYNOPSIS + In MyApp.pm- + + use Catalyst qw/ + Authentication + Session + Session::Store::FastMmap + Session::State::Cookie + /; + + Somewhere in myapp.conf- + + + default_realm openid + + + + class OpenID + + ua_class LWP::UserAgent + + + + + Or in your myapp.yml if you're using YAML instead- + + Plugin::Authentication: + default_realm: openid + realms: + openid: + credential: + class: OpenID + ua_class: LWP::UserAgent + + In a controller, perhaps "Root::openid"- + + sub openid : Local { + my($self, $c) = @_; + + if ( $c->authenticate() ) + { + $c->flash(message => "You signed in with OpenID!"); + $c->res->redirect( $c->uri_for('/') ); + } + else + { + # Present OpenID form. + } + } + + And a Template to match in "openid.tt"- + +
+ + +
+ +DESCRIPTION + This is the third OpenID related authentication piece for Catalyst. The + first — Catalyst::Plugin::Authentication::OpenID by Benjamin Trott — was + deprecated by the second — + Catalyst::Plugin::Authentication::Credential::OpenID by Tatsuhiko + Miyagawa — and this is an attempt to deprecate both by conforming to the + newish, at the time of this module's inception, realm-based + authentication in Catalyst::Plugin::Authentication. + + 1. Catalyst::Plugin::Authentication::OpenID + 2. Catalyst::Plugin::Authentication::Credential::OpenID + 3. Catalyst::Authentication::Credential::OpenID + + The benefit of this version is that you can use an arbitrary number of + authentication systems in your Catalyst application and configure and + call all of them in the same way. + + Note that both earlier versions of OpenID authentication use the method + "authenticate_openid()". This module uses "authenticate()" and relies on + you to specify the realm. You can specify the realm as the default in + the configuration or inline with each "authenticate()" call; more below. + + This module functions quite differently internally from the others. See + Catalyst::Plugin::Authentication::Internals for more about this + implementation. + +METHODS + $c->authenticate({},"your_openid_realm"); + Call to authenticate the user via OpenID. Returns false if + authorization is unsuccessful. Sets the user into the session and + returns the user object if authentication succeeds. + + You can see in the call above that the authentication hash is empty. + The implicit OpenID parameter is, as the 2.0 specification says it + SHOULD be, openid_identifier. You can set it anything you like in + your realm configuration, though, under the key "openid_field". If + you call "authenticate()" with the empty info hash and no configured + "openid_field" then only "openid_identifier" is checked. + + It implicitly does this (sort of, it checks the request method too)- + + my $claimed_uri = $c->req->params->{openid_identifier}; + $c->authenticate({openid_identifier => $claimed_uri}); + + Catalyst::Authentication::Credential::OpenID->new() + You will never call this. Catalyst does it for you. The only + important thing you might like to know about it is that it merges + its realm configuration with its configuration proper. If this + doesn't mean anything to you, don't worry. + + USER METHODS + Currently the only supported user class is + Catalyst::Plugin::Authentication::User::Hash. + + $c->user->url + $c->user->display + $c->user->rss + $c->user->atom + $c->user->foaf + $c->user->declared_rss + $c->user->declared_atom + $c->user->declared_foaf + $c->user->foafmaker + + See Net::OpenID::VerifiedIdentity for details. + +CONFIGURATION + Catalyst authentication is now configured entirely from your + application's configuration. Do not, for example, put + "Credential::OpenID" into your "use Catalyst ..." statement. Instead, + tell your application that in one of your authentication realms you will + use the credential. + + In your application the following will give you two different + authentication realms. One called "members" which authenticates with + clear text passwords and one called "openid" which uses... uh, OpenID. + + __PACKAGE__->config + ( name => "MyApp", + "Plugin::Authentication" => { + default_realm => "members", + realms => { + members => { + credential => { + class => "Password", + password_field => "password", + password_type => "clear" + }, + store => { + class => "Minimal", + users => { + paco => { + password => "l4s4v3n7ur45", + }, + } + } + }, + openid => { + consumer_secret => "Don't bother setting", + ua_class => "LWP::UserAgent", + ua_args => { + whitelisted_hosts => [qw/ 127.0.0.1 localhost /], + }, + credential => { + class => "OpenID", + store => { + class => "OpenID", + }, + }, + extensions => [ + 'http://openid.net/extensions/sreg/1.1', + { + required => 'email', + optional => 'fullname,nickname,timezone', + }, + ], + }, + }, + } + ); + + This is the same configuration in the default Catalyst configuration + format from Config::General. + + name MyApp + + default_realm members + + + + class Minimal + + + password l4s4v3n7ur45 + + + + + password_field password + password_type clear + class Password + + + + + whitelisted_hosts 127.0.0.1 + whitelisted_hosts localhost + + consumer_secret Don't bother setting + ua_class LWP::UserAgent + + + class OpenID + + class OpenID + + + http://openid.net/extensions/sreg/1.1 + required email + optional fullname,nickname,timezone + + + + + + And now, the same configuration in YAML. NB: YAML is whitespace + sensitive. + + name: MyApp + Plugin::Authentication: + default_realm: members + realms: + members: + credential: + class: Password + password_field: password + password_type: clear + store: + class: Minimal + users: + paco: + password: l4s4v3n7ur45 + openid: + credential: + class: OpenID + store: + class: OpenID + consumer_secret: Don't bother setting + ua_class: LWP::UserAgent + ua_args: + whitelisted_hosts: + - 127.0.0.1 + - localhost + extensions: + - http://openid.net/extensions/sreg/1.1 + - required: email + optional: fullname,nickname,timezone + + NB: There is no OpenID store yet. + + EXTENSIONS TO OPENID + The Simple Registration----(SREG) + extension to OpenID is supported in the Net::OpenID family now. + Experimental support for it is included here as of v0.12. SREG is the + only supported extension in OpenID 1.1. It's experimental in the sense + it's a new interface and barely tested. Support for OpenID extensions is + here to stay. + + MORE ON CONFIGURATION + These are set in your realm. See above. + + ua_args and ua_class + LWPx::ParanoidAgent is the default agent — "ua_class" — if it's + available, LWP::UserAgent if not. You don't have to set it. I + recommend that you do not override it. You can with any well behaved + LWP::UserAgent. You probably should not. LWPx::ParanoidAgent buys + you many defenses and extra security checks. When you allow your + application users freedom to initiate external requests, you open an + avenue for DoS (denial of service) attacks. LWPx::ParanoidAgent + defends against this. LWP::UserAgent and any regular subclass of it + will not. + + consumer_secret + The underlying Net::OpenID::Consumer object is seeded with a secret. + If it's important to you to set your own, you can. The default uses + this package name + its version + the sorted configuration keys of + your Catalyst application (chopped at 255 characters if it's + longer). This should generally be superior to any fixed string. + +TODO + Option to suppress fatals. + + Support more of the new methods in the Net::OpenID kit. + + There are some interesting implications with this sort of setup. Does a + user aggregate realms or can a user be signed in under more than one + realm? The documents could contain a recipe of the self-answering OpenID + end-point that is in the tests. + + Debug statements need to be both expanded and limited via realm + configuration. + + Better diagnostics in errors. Debug info at all consumer calls. + + Roles from provider domains? Mapped? Direct? A generic "openid" + auto_role? + +THANKS + To Benjamin Trott (Catalyst::Plugin::Authentication::OpenID), Tatsuhiko + Miyagawa (Catalyst::Plugin::Authentication::Credential::OpenID), Brad + Fitzpatrick for the great OpenID stuff, Martin Atkins for picking up the + code to handle OpenID 2.0, and Jay Kuri and everyone else who has made + Catalyst such a wonderful framework. + + Menno Blom provided a bug fix and the hook to use OpenID extensions. + +LICENSE AND COPYRIGHT + Copyright (c) 2008-2009, Ashley Pond V "". Some of + Tatsuhiko Miyagawa's work is reused here. + + This module is free software; you can redistribute it and modify it + under the same terms as Perl itself. See perlartistic. + +DISCLAIMER OF WARRANTY + Because this software is licensed free of charge, there is no warranty + for the software, to the extent permitted by applicable law. Except when + otherwise stated in writing the copyright holders and other parties + provide the software "as is" without warranty of any kind, either + expressed or implied, including, but not limited to, the implied + warranties of merchantability and fitness for a particular purpose. The + entire risk as to the quality and performance of the software is with + you. Should the software prove defective, you assume the cost of all + necessary servicing, repair, or correction. + + In no event unless required by applicable law or agreed to in writing + will any copyright holder, or any other party who may modify or + redistribute the software as permitted by the above license, be liable + to you for damages, including any general, special, incidental, or + consequential damages arising out of the use or inability to use the + software (including but not limited to loss of data or data being + rendered inaccurate or losses sustained by you or third parties or a + failure of the software to operate with any other software), even if + such holder or other party has been advised of the possibility of such + damages. + +SEE ALSO + OpenID + Net::OpenID::Server, Net::OpenID::VerifiedIdentity, + Net::OpenID::Consumer, , + , and + . + + Catalyst Authentication + Catalyst, Catalyst::Plugin::Authentication, + Catalyst::Manual::Tutorial::Authorization, and + Catalyst::Manual::Tutorial::Authentication. + + Catalyst Configuration + Catalyst::Plugin::ConfigLoader, Config::General, and YAML. + + Miscellaneous + Catalyst::Manual::Tutorial, Template, LWPx::ParanoidAgent.