README

   1 NAME
   2     Catalyst::Authentication::Credential::OpenID - OpenID credential for
   3     Catalyst::Plugin::Authentication framework.
   4
   5 VERSION
   6     0.15
   7
   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.
  15
  16     As previously noted, "EXTENSIONS TO OPENID", I have not tested the
  17     extensions. I would be grateful for any feedback or, better, tests.
  18
  19   FATALS
  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.
  26
  27 SYNOPSIS
  28     In MyApp.pm-
  29
  30      use Catalyst qw/
  31         Authentication
  32         Session
  33         Session::Store::FastMmap
  34         Session::State::Cookie
  35      /;
  36
  37     Somewhere in myapp.conf-
  38
  39      <Plugin::Authentication>
  40          default_realm   openid
  41          <realms>
  42              <openid>
  43                  <credential>
  44                      class   OpenID
  45                      ua_class   LWP::UserAgent
  46                  </credential>
  47              </openid>
  48          </realms>
  49      </Plugin::Authentication>
  50
  51     Or in your myapp.yml if you're using YAML instead-
  52
  53      Plugin::Authentication:
  54        default_realm: openid
  55        realms:
  56          openid:
  57            credential:
  58              class: OpenID
  59              ua_class: LWP::UserAgent
  60
  61     In a controller, perhaps "Root::openid"-
  62
  63      sub openid : Local {
  64           my($self, $c) = @_;
  65
  66           if ( $c->authenticate() )
  67           {
  68               $c->flash(message => "You signed in with OpenID!");
  69               $c->res->redirect( $c->uri_for('/') );
  70           }
  71           else
  72           {
  73               # Present OpenID form.
  74           }
  75      }
  76
  77     And a Template to match in "openid.tt"-
  78
  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" />
  82      </form>
  83
  84 DESCRIPTION
  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.
  92
  93      1. Catalyst::Plugin::Authentication::OpenID
  94      2. Catalyst::Plugin::Authentication::Credential::OpenID
  95      3. Catalyst::Authentication::Credential::OpenID
  96
  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.
 100
 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.
 105
 106     This module functions quite differently internally from the others. See
 107     Catalyst::Plugin::Authentication::Internals for more about this
 108     implementation.
 109
 110 METHODS
 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.
 115
 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.
 122
 123         It implicitly does this (sort of, it checks the request method too)-
 124
 125          my $claimed_uri = $c->req->params->{openid_identifier};
 126          $c->authenticate({openid_identifier => $claimed_uri});
 127
 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.
 133
 134   USER METHODS
 135     Currently the only supported user class is
 136     Catalyst::Plugin::Authentication::User::Hash.
 137
 138     $c->user->url
 139     $c->user->display
 140     $c->user->rss
 141     $c->user->atom
 142     $c->user->foaf
 143     $c->user->declared_rss
 144     $c->user->declared_atom
 145     $c->user->declared_foaf
 146     $c->user->foafmaker
 147
 148     See Net::OpenID::VerifiedIdentity for details.
 149
 150 CONFIGURATION
 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
 155     use the credential.
 156
 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.
 160
 161      __PACKAGE__->config
 162         ( name => "MyApp",
 163           "Plugin::Authentication" => {
 164               default_realm => "members",
 165               realms => {
 166                   members => {
 167                       credential => {
 168                           class => "Password",
 169                           password_field => "password",
 170                           password_type => "clear"
 171                           },
 172                               store => {
 173                                   class => "Minimal",
 174                                   users => {
 175                                       paco => {
 176                                           password => "l4s4v3n7ur45",
 177                                       },
 178                                   }
 179                               }
 180                   },
 181                   openid => {
 182                       credential => {
 183                           class => "OpenID",
 184                           store => {
 185                               class => "OpenID",
 186                           },
 187                           consumer_secret => "Don't bother setting",
 188                           ua_class => "LWP::UserAgent",
 189                           # whitelist is only relevant for LWPx::ParanoidAgent
 190                           ua_args => {
 191                               whitelisted_hosts => [qw/ 127.0.0.1 localhost /],
 192                           },
 193                           extensions => [
 194                               'http://openid.net/extensions/sreg/1.1',
 195                               {
 196                                required => 'email',
 197                                optional => 'fullname,nickname,timezone',
 198                               },
 199                           ],
 200                       },
 201                   },
 202               },
 203           }
 204         );
 205
 206     This is the same configuration in the default Catalyst configuration
 207     format from Config::General.
 208
 209      name   MyApp
 210      <Plugin::Authentication>
 211          default_realm   members
 212          <realms>
 213              <members>
 214                  <store>
 215                      class   Minimal
 216                      <users>
 217                          <paco>
 218                              password   l4s4v3n7ur45
 219                          </paco>
 220                      </users>
 221                  </store>
 222                  <credential>
 223                      password_field   password
 224                      password_type   clear
 225                      class   Password
 226                  </credential>
 227              </members>
 228              <openid>
 229                  <credential>
 230                      <store>
 231                          class   OpenID
 232                      </store>
 233                      class   OpenID
 234                      <ua_args>
 235                          whitelisted_hosts   127.0.0.1
 236                          whitelisted_hosts   localhost
 237                      </ua_args>
 238                      consumer_secret   Don't bother setting
 239                      ua_class   LWP::UserAgent
 240                      <extensions>
 241                          http://openid.net/extensions/sreg/1.1
 242                          required   email
 243                          optional   fullname,nickname,timezone
 244                      </extensions>
 245                  </credential>
 246              </openid>
 247          </realms>
 248      </Plugin::Authentication>
 249
 250     And now, the same configuration in YAML. NB: YAML is whitespace
 251     sensitive.
 252
 253      name: MyApp
 254      Plugin::Authentication:
 255        default_realm: members
 256        realms:
 257          members:
 258            credential:
 259              class: Password
 260              password_field: password
 261              password_type: clear
 262            store:
 263              class: Minimal
 264              users:
 265                paco:
 266                  password: l4s4v3n7ur45
 267          openid:
 268            credential:
 269              class: OpenID
 270              store:
 271                class: OpenID
 272              consumer_secret: Don't bother setting
 273              ua_class: LWP::UserAgent
 274              ua_args:
 275                # whitelist is only relevant for LWPx::ParanoidAgent
 276                whitelisted_hosts:
 277                  - 127.0.0.1
 278                  - localhost
 279              extensions:
 280                  - http://openid.net/extensions/sreg/1.1
 281                  - required: email
 282                    optional: fullname,nickname,timezone
 283
 284     NB: There is no OpenID store yet.
 285
 286   EXTENSIONS TO OPENID
 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
 292     here to stay.
 293
 294   MORE ON CONFIGURATION
 295     ua_args and ua_class
 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
 304         will not.
 305
 306     consumer_secret
 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.
 312
 313 TODO
 314     Option to suppress fatals.
 315
 316     Support more of the new methods in the Net::OpenID kit.
 317
 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.
 322
 323     Debug statements need to be both expanded and limited via realm
 324     configuration.
 325
 326     Better diagnostics in errors. Debug info at all consumer calls.
 327
 328     Roles from provider domains? Mapped? Direct? A generic "openid"
 329     auto_role?
 330
 331 THANKS
 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.
 337
 338     Menno Blom provided a bug fix and the hook to use OpenID extensions.
 339
 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.
 343
 344     This module is free software; you can redistribute it and modify it
 345     under the same terms as Perl itself. See perlartistic.
 346
 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.
 357
 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
 367     damages.
 368
 369 SEE ALSO
 370     OpenID
 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>.
 375
 376     Catalyst Authentication
 377         Catalyst, Catalyst::Plugin::Authentication,
 378         Catalyst::Manual::Tutorial::Authorization, and
 379         Catalyst::Manual::Tutorial::Authentication.
 380
 381     Catalyst Configuration
 382         Catalyst::Plugin::ConfigLoader, Config::General, and YAML.
 383
 384     Miscellaneous
 385         Catalyst::Manual::Tutorial, Template, LWPx::ParanoidAgent.
 386
 387 POD ERRORS
 388     Hey! The above document had some coding errors, which are explained
 389     below:
 390
 391     Around line 464:
 392         '=item' outside of any '=over'
 393