2 Catalyst::Authentication::Credential::OpenID - OpenID credential for
3 Catalyst::Plugin::Authentication framework.
8 BACKWARDS COMPATIBILITY CHANGES
9 EXTENSION_ARGS v EXTENSIONS
10 NB: The extensions were previously configured under the key
11 "extension_args". They are now configured under "extensions". This
12 prevents the need for double configuration but it breaks extensions in
13 your application if you do not change the name. The old version is
14 supported for now but may be phased out at any time.
16 As previously noted, "EXTENSIONS TO OPENID", I have not tested the
17 extensions. I would be grateful for any feedback or, better, tests.
20 The problems encountered by failed OpenID operations have always been
21 fatals in the past. This is unexpected behavior for most users as it
22 differs from other credentials. Authentication errors here are no longer
23 fatal. Debug/error output is improved to offset the loss of information.
24 If for some reason you would prefer the legacy/fatal behavior, set the
25 configuration variable "errors_are_fatal" to a true value.
33 Session::Store::FastMmap
34 Session::State::Cookie
37 Somewhere in myapp.conf-
39 <Plugin::Authentication>
45 ua_class LWP::UserAgent
49 </Plugin::Authentication>
51 Or in your myapp.yml if you're using YAML instead-
53 Plugin::Authentication:
59 ua_class: LWP::UserAgent
61 In a controller, perhaps "Root::openid"-
66 if ( $c->authenticate() )
68 $c->flash(message => "You signed in with OpenID!");
69 $c->res->redirect( $c->uri_for('/') );
73 # Present OpenID form.
77 And a Template to match in "openid.tt"-
79 <form action="[% c.uri_for('/openid') %]" method="GET" name="openid">
80 <input type="text" name="openid_identifier" class="openid" />
81 <input type="submit" value="Sign in with OpenID" />
85 This is the third OpenID related authentication piece for Catalyst. The
86 first — Catalyst::Plugin::Authentication::OpenID by Benjamin Trott — was
87 deprecated by the second —
88 Catalyst::Plugin::Authentication::Credential::OpenID by Tatsuhiko
89 Miyagawa — and this is an attempt to deprecate both by conforming to the
90 newish, at the time of this module's inception, realm-based
91 authentication in Catalyst::Plugin::Authentication.
93 1. Catalyst::Plugin::Authentication::OpenID
94 2. Catalyst::Plugin::Authentication::Credential::OpenID
95 3. Catalyst::Authentication::Credential::OpenID
97 The benefit of this version is that you can use an arbitrary number of
98 authentication systems in your Catalyst application and configure and
99 call all of them in the same way.
101 Note that both earlier versions of OpenID authentication use the method
102 "authenticate_openid()". This module uses "authenticate()" and relies on
103 you to specify the realm. You can specify the realm as the default in
104 the configuration or inline with each "authenticate()" call; more below.
106 This module functions quite differently internally from the others. See
107 Catalyst::Plugin::Authentication::Internals for more about this
111 $c->authenticate({},"your_openid_realm");
112 Call to authenticate the user via OpenID. Returns false if
113 authorization is unsuccessful. Sets the user into the session and
114 returns the user object if authentication succeeds.
116 You can see in the call above that the authentication hash is empty.
117 The implicit OpenID parameter is, as the 2.0 specification says it
118 SHOULD be, openid_identifier. You can set it anything you like in
119 your realm configuration, though, under the key "openid_field". If
120 you call "authenticate()" with the empty info hash and no configured
121 "openid_field" then only "openid_identifier" is checked.
123 It implicitly does this (sort of, it checks the request method too)-
125 my $claimed_uri = $c->req->params->{openid_identifier};
126 $c->authenticate({openid_identifier => $claimed_uri});
128 Catalyst::Authentication::Credential::OpenID->new()
129 You will never call this. Catalyst does it for you. The only
130 important thing you might like to know about it is that it merges
131 its realm configuration with its configuration proper. If this
132 doesn't mean anything to you, don't worry.
135 Currently the only supported user class is
136 Catalyst::Plugin::Authentication::User::Hash.
143 $c->user->declared_rss
144 $c->user->declared_atom
145 $c->user->declared_foaf
148 See Net::OpenID::VerifiedIdentity for details.
151 Catalyst authentication is now configured entirely from your
152 application's configuration. Do not, for example, put
153 "Credential::OpenID" into your "use Catalyst ..." statement. Instead,
154 tell your application that in one of your authentication realms you will
157 In your application the following will give you two different
158 authentication realms. One called "members" which authenticates with
159 clear text passwords and one called "openid" which uses... uh, OpenID.
163 "Plugin::Authentication" => {
164 default_realm => "members",
169 password_field => "password",
170 password_type => "clear"
176 password => "l4s4v3n7ur45",
187 consumer_secret => "Don't bother setting",
188 ua_class => "LWP::UserAgent",
189 # whitelist is only relevant for LWPx::ParanoidAgent
191 whitelisted_hosts => [qw/ 127.0.0.1 localhost /],
194 'http://openid.net/extensions/sreg/1.1',
197 optional => 'fullname,nickname,timezone',
206 This is the same configuration in the default Catalyst configuration
207 format from Config::General.
210 <Plugin::Authentication>
211 default_realm members
218 password l4s4v3n7ur45
223 password_field password
235 whitelisted_hosts 127.0.0.1
236 whitelisted_hosts localhost
238 consumer_secret Don't bother setting
239 ua_class LWP::UserAgent
241 http://openid.net/extensions/sreg/1.1
243 optional fullname,nickname,timezone
248 </Plugin::Authentication>
250 And now, the same configuration in YAML. NB: YAML is whitespace
254 Plugin::Authentication:
255 default_realm: members
260 password_field: password
266 password: l4s4v3n7ur45
272 consumer_secret: Don't bother setting
273 ua_class: LWP::UserAgent
275 # whitelist is only relevant for LWPx::ParanoidAgent
280 - http://openid.net/extensions/sreg/1.1
282 optional: fullname,nickname,timezone
284 NB: There is no OpenID store yet.
287 The Simple Registration--<http://openid.net/extensions/sreg/1.1>--(SREG)
288 extension to OpenID is supported in the Net::OpenID family now.
289 Experimental support for it is included here as of v0.12. SREG is the
290 only supported extension in OpenID 1.1. It's experimental in the sense
291 it's a new interface and barely tested. Support for OpenID extensions is
294 MORE ON CONFIGURATION
296 LWPx::ParanoidAgent is the default agent — "ua_class" — if it's
297 available, LWP::UserAgent if not. You don't have to set it. I
298 recommend that you do not override it. You can with any well behaved
299 LWP::UserAgent. You probably should not. LWPx::ParanoidAgent buys
300 you many defenses and extra security checks. When you allow your
301 application users freedom to initiate external requests, you open an
302 avenue for DoS (denial of service) attacks. LWPx::ParanoidAgent
303 defends against this. LWP::UserAgent and any regular subclass of it
307 The underlying Net::OpenID::Consumer object is seeded with a secret.
308 If it's important to you to set your own, you can. The default uses
309 this package name + its version + the sorted configuration keys of
310 your Catalyst application (chopped at 255 characters if it's
311 longer). This should generally be superior to any fixed string.
314 Option to suppress fatals.
316 Support more of the new methods in the Net::OpenID kit.
318 There are some interesting implications with this sort of setup. Does a
319 user aggregate realms or can a user be signed in under more than one
320 realm? The documents could contain a recipe of the self-answering OpenID
321 end-point that is in the tests.
323 Debug statements need to be both expanded and limited via realm
326 Better diagnostics in errors. Debug info at all consumer calls.
328 Roles from provider domains? Mapped? Direct? A generic "openid"
332 To Benjamin Trott (Catalyst::Plugin::Authentication::OpenID), Tatsuhiko
333 Miyagawa (Catalyst::Plugin::Authentication::Credential::OpenID), Brad
334 Fitzpatrick for the great OpenID stuff, Martin Atkins for picking up the
335 code to handle OpenID 2.0, and Jay Kuri and everyone else who has made
336 Catalyst such a wonderful framework.
338 Menno Blom provided a bug fix and the hook to use OpenID extensions.
340 LICENSE AND COPYRIGHT
341 Copyright (c) 2008-2009, Ashley Pond V "<ashley@cpan.org>". Some of
342 Tatsuhiko Miyagawa's work is reused here.
344 This module is free software; you can redistribute it and modify it
345 under the same terms as Perl itself. See perlartistic.
347 DISCLAIMER OF WARRANTY
348 Because this software is licensed free of charge, there is no warranty
349 for the software, to the extent permitted by applicable law. Except when
350 otherwise stated in writing the copyright holders and other parties
351 provide the software "as is" without warranty of any kind, either
352 expressed or implied, including, but not limited to, the implied
353 warranties of merchantability and fitness for a particular purpose. The
354 entire risk as to the quality and performance of the software is with
355 you. Should the software prove defective, you assume the cost of all
356 necessary servicing, repair, or correction.
358 In no event unless required by applicable law or agreed to in writing
359 will any copyright holder, or any other party who may modify or
360 redistribute the software as permitted by the above license, be liable
361 to you for damages, including any general, special, incidental, or
362 consequential damages arising out of the use or inability to use the
363 software (including but not limited to loss of data or data being
364 rendered inaccurate or losses sustained by you or third parties or a
365 failure of the software to operate with any other software), even if
366 such holder or other party has been advised of the possibility of such
371 Net::OpenID::Server, Net::OpenID::VerifiedIdentity,
372 Net::OpenID::Consumer, <http://openid.net/>,
373 <http://openid.net/developers/specs/>, and
374 <http://openid.net/extensions/sreg/1.1>.
376 Catalyst Authentication
377 Catalyst, Catalyst::Plugin::Authentication,
378 Catalyst::Manual::Tutorial::Authorization, and
379 Catalyst::Manual::Tutorial::Authentication.
381 Catalyst Configuration
382 Catalyst::Plugin::ConfigLoader, Config::General, and YAML.
385 Catalyst::Manual::Tutorial, Template, LWPx::ParanoidAgent.
388 Hey! The above document had some coding errors, which are explained
392 '=item' outside of any '=over'