NAME
Catalyst::Authentication::Credential::OpenID - OpenID credential for Catalyst::Plugin::Authentication framework.
VERSION
0.16
BACKWARDS COMPATIBILITY CHANGES
EXTENSION_ARGS v EXTENSIONS
NB: The extensions 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.
As previously noted, "EXTENSIONS TO OPENID", I have not tested the extensions. I would be grateful for any feedback or, better, tests.
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.
SYNOPSIS
In MyApp.pm-
use Catalyst qw/
Authentication
Session
Session::Store::FastMmap
Session::State::Cookie
/;
Somewhere in myapp.conf-
<Plugin::Authentication>
default_realm openid
<realms>
<openid>
<credential>
class OpenID
ua_class LWP::UserAgent
</credential>
</openid>
</realms>
</Plugin::Authentication>
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"-
<form action="[% c.uri_for('/openid') %]" method="GET" name="openid">
<input type="text" name="openid_identifier" class="openid" />
<input type="submit" value="Sign in with OpenID" />
</form>
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.
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 => {
credential => {
class => "OpenID",
store => {
class => "OpenID",
},
consumer_secret => "Don't bother setting",
ua_class => "LWP::UserAgent",
# whitelist is only relevant for LWPx::ParanoidAgent
ua_args => {
whitelisted_hosts => [qw/ 127.0.0.1 localhost /],
},
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
<Plugin::Authentication>
default_realm members
<realms>
<members>
<store>
class Minimal
<users>
<paco>
password l4s4v3n7ur45
</paco>
</users>
</store>
<credential>
password_field password
password_type clear
class Password
</credential>
</members>
<openid>
<credential>
<store>
class OpenID
</store>
class OpenID
<ua_args>
whitelisted_hosts 127.0.0.1
whitelisted_hosts localhost
</ua_args>
consumer_secret Don't bother setting
ua_class LWP::UserAgent
<extensions>
http://openid.net/extensions/sreg/1.1
required email
optional fullname,nickname,timezone
</extensions>
</credential>
</openid>
</realms>
</Plugin::Authentication>
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:
# whitelist is only relevant for LWPx::ParanoidAgent
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--<http://openid.net/extensions/sreg/1.1>--(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
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 "<ashley@cpan.org>". 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, <http://openid.net/>,
<http://openid.net/developers/specs/>, and
<http://openid.net/extensions/sreg/1.1>.
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.