README

   1 NAME
   2     Catalyst::Authentication::Credential::OpenID - OpenID credential for
   3     Catalyst::Plugin::Authentication framework.
   4
   5 VERSION
   6     0.14_03
   7
   8 BACKWARDS COMPATIBILITY CHANGES
   9   EXTENTION_ARGS v EXTENSIONS
  10     NB: The extenstions 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                  </credential>
  46                  ua_class   LWP::UserAgent
  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                       consumer_secret => "Don't bother setting",
 183                       ua_class => "LWP::UserAgent",
 184                       ua_args => {
 185                           whitelisted_hosts => [qw/ 127.0.0.1 localhost /],
 186                       },
 187                       credential => {
 188                           class => "OpenID",
 189                           store => {
 190                               class => "OpenID",
 191                           },
 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     This is the same configuration in the default Catalyst configuration
 206     format from Config::General.
 207
 208      name   MyApp
 209      <Plugin::Authentication>
 210          default_realm   members
 211          <realms>
 212              <members>
 213                  <store>
 214                      class   Minimal
 215                      <users>
 216                          <paco>
 217                              password   l4s4v3n7ur45
 218                          </paco>
 219                      </users>
 220                  </store>
 221                  <credential>
 222                      password_field   password
 223                      password_type   clear
 224                      class   Password
 225                  </credential>
 226              </members>
 227              <openid>
 228                  <ua_args>
 229                      whitelisted_hosts   127.0.0.1
 230                      whitelisted_hosts   localhost
 231                  </ua_args>
 232                  consumer_secret   Don't bother setting
 233                  ua_class   LWP::UserAgent
 234                  <credential>
 235                      <store>
 236                          class   OpenID
 237                      </store>
 238                      class   OpenID
 239                  </credential>
 240                  <extensions>
 241                      http://openid.net/extensions/sreg/1.1
 242                      required   email
 243                      optional   fullname,nickname,timezone
 244                  </extensions>
 245              </openid>
 246          </realms>
 247      </Plugin::Authentication>
 248
 249     And now, the same configuration in YAML. NB: YAML is whitespace
 250     sensitive.
 251
 252      name: MyApp
 253      Plugin::Authentication:
 254        default_realm: members
 255        realms:
 256          members:
 257            credential:
 258              class: Password
 259              password_field: password
 260              password_type: clear
 261            store:
 262              class: Minimal
 263              users:
 264                paco:
 265                  password: l4s4v3n7ur45
 266          openid:
 267            credential:
 268              class: OpenID
 269              store:
 270                class: OpenID
 271            consumer_secret: Don't bother setting
 272            ua_class: LWP::UserAgent
 273            ua_args:
 274              whitelisted_hosts:
 275                - 127.0.0.1
 276                - localhost
 277            extensions:
 278                - http://openid.net/extensions/sreg/1.1
 279                - required: email
 280                  optional: fullname,nickname,timezone
 281
 282     NB: There is no OpenID store yet.
 283
 284   EXTENSIONS TO OPENID
 285     The Simple Registration--<http://openid.net/extensions/sreg/1.1>--(SREG)
 286     extension to OpenID is supported in the Net::OpenID family now.
 287     Experimental support for it is included here as of v0.12. SREG is the
 288     only supported extension in OpenID 1.1. It's experimental in the sense
 289     it's a new interface and barely tested. Support for OpenID extensions is
 290     here to stay.
 291
 292   MORE ON CONFIGURATION
 293     These are set in your realm. See above.
 294
 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