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.