README

   1 NAME
   2     Catalyst::Authentication::Credential::OpenID - OpenID credential for
   3     Catalyst::Plugin::Authentication framework.
   4
   5 VERSION
   6     0.14_02
   7
   8 BACKWARDS COMPATIBILITY CHANGE
   9     NB: The extenstions were previously configured under the key
  10     "extension_args". They are now configured under "extensions". This
  11     prevents the need for double configuration but it breaks extensions in
  12     your application if you do not change the name. The old version is
  13     supported for now but may be phased out at any time.
  14
  15     As previously noted, "EXTENSIONS TO OPENID", I have not tested the
  16     extensions. I would be grateful for any feedback or, better, tests.
  17
  18 SYNOPSIS
  19     In MyApp.pm-
  20
  21      use Catalyst qw/
  22         Authentication
  23         Session
  24         Session::Store::FastMmap
  25         Session::State::Cookie
  26      /;
  27
  28     Somewhere in myapp.conf-
  29
  30      <Plugin::Authentication>
  31          default_realm   openid
  32          <realms>
  33              <openid>
  34                  <credential>
  35                      class   OpenID
  36                  </credential>
  37                  ua_class   LWP::UserAgent
  38              </openid>
  39          </realms>
  40      </Plugin::Authentication>
  41
  42     Or in your myapp.yml if you're using YAML instead-
  43
  44      Plugin::Authentication:
  45        default_realm: openid
  46        realms:
  47          openid:
  48            credential:
  49              class: OpenID
  50            ua_class: LWP::UserAgent
  51
  52     In a controller, perhaps "Root::openid"-
  53
  54      sub openid : Local {
  55           my($self, $c) = @_;
  56
  57           if ( $c->authenticate() )
  58           {
  59               $c->flash(message => "You signed in with OpenID!");
  60               $c->res->redirect( $c->uri_for('/') );
  61           }
  62           else
  63           {
  64               # Present OpenID form.
  65           }
  66      }
  67
  68     And a Template to match in "openid.tt"-
  69
  70      <form action="[% c.uri_for('/openid') %]" method="GET" name="openid">
  71      <input type="text" name="openid_identifier" class="openid" />
  72      <input type="submit" value="Sign in with OpenID" />
  73      </form>
  74
  75 DESCRIPTION
  76     This is the third OpenID related authentication piece for Catalyst. The
  77     first — Catalyst::Plugin::Authentication::OpenID by Benjamin Trott — was
  78     deprecated by the second —
  79     Catalyst::Plugin::Authentication::Credential::OpenID by Tatsuhiko
  80     Miyagawa — and this is an attempt to deprecate both by conforming to the
  81     newish, at the time of this module's inception, realm-based
  82     authentication in Catalyst::Plugin::Authentication.
  83
  84      1. Catalyst::Plugin::Authentication::OpenID
  85      2. Catalyst::Plugin::Authentication::Credential::OpenID
  86      3. Catalyst::Authentication::Credential::OpenID
  87
  88     The benefit of this version is that you can use an arbitrary number of
  89     authentication systems in your Catalyst application and configure and
  90     call all of them in the same way.
  91
  92     Note that both earlier versions of OpenID authentication use the method
  93     "authenticate_openid()". This module uses "authenticate()" and relies on
  94     you to specify the realm. You can specify the realm as the default in
  95     the configuration or inline with each "authenticate()" call; more below.
  96
  97     This module functions quite differently internally from the others. See
  98     Catalyst::Plugin::Authentication::Internals for more about this
  99     implementation.
 100
 101 METHODS
 102     $c->authenticate({},"your_openid_realm");
 103         Call to authenticate the user via OpenID. Returns false if
 104         authorization is unsuccessful. Sets the user into the session and
 105         returns the user object if authentication succeeds.
 106
 107         You can see in the call above that the authentication hash is empty.
 108         The implicit OpenID parameter is, as the 2.0 specification says it
 109         SHOULD be, openid_identifier. You can set it anything you like in
 110         your realm configuration, though, under the key "openid_field". If
 111         you call "authenticate()" with the empty info hash and no configured
 112         "openid_field" then only "openid_identifier" is checked.
 113
 114         It implicitly does this (sort of, it checks the request method too)-
 115
 116          my $claimed_uri = $c->req->params->{openid_identifier};
 117          $c->authenticate({openid_identifier => $claimed_uri});
 118
 119     Catalyst::Authentication::Credential::OpenID->new()
 120         You will never call this. Catalyst does it for you. The only
 121         important thing you might like to know about it is that it merges
 122         its realm configuration with its configuration proper. If this
 123         doesn't mean anything to you, don't worry.
 124
 125   USER METHODS
 126     Currently the only supported user class is
 127     Catalyst::Plugin::Authentication::User::Hash.
 128
 129     $c->user->url
 130     $c->user->display
 131     $c->user->rss
 132     $c->user->atom
 133     $c->user->foaf
 134     $c->user->declared_rss
 135     $c->user->declared_atom
 136     $c->user->declared_foaf
 137     $c->user->foafmaker
 138
 139     See Net::OpenID::VerifiedIdentity for details.
 140
 141 CONFIGURATION
 142     Catalyst authentication is now configured entirely from your
 143     application's configuration. Do not, for example, put
 144     "Credential::OpenID" into your "use Catalyst ..." statement. Instead,
 145     tell your application that in one of your authentication realms you will
 146     use the credential.
 147
 148     In your application the following will give you two different
 149     authentication realms. One called "members" which authenticates with
 150     clear text passwords and one called "openid" which uses... uh, OpenID.
 151
 152      __PACKAGE__->config
 153         ( name => "MyApp",
 154           "Plugin::Authentication" => {
 155               default_realm => "members",
 156               realms => {
 157                   members => {
 158                       credential => {
 159                           class => "Password",
 160                           password_field => "password",
 161                           password_type => "clear"
 162                           },
 163                               store => {
 164                                   class => "Minimal",
 165                                   users => {
 166                                       paco => {
 167                                           password => "l4s4v3n7ur45",
 168                                       },
 169                                   }
 170                               }
 171                   },
 172                   openid => {
 173                       consumer_secret => "Don't bother setting",
 174                       ua_class => "LWP::UserAgent",
 175                       ua_args => {
 176                           whitelisted_hosts => [qw/ 127.0.0.1 localhost /],
 177                       },
 178                       credential => {
 179                           class => "OpenID",
 180                           store => {
 181                               class => "OpenID",
 182                           },
 183                       },
 184                       extensions => [
 185                           'http://openid.net/extensions/sreg/1.1',
 186                           {
 187                            required => 'email',
 188                            optional => 'fullname,nickname,timezone',
 189                           },
 190                       ],
 191                   },
 192               },
 193           }
 194         );
 195
 196     This is the same configuration in the default Catalyst configuration
 197     format from Config::General.
 198
 199      name   MyApp
 200      <Plugin::Authentication>
 201          default_realm   members
 202          <realms>
 203              <members>
 204                  <store>
 205                      class   Minimal
 206                      <users>
 207                          <paco>
 208                              password   l4s4v3n7ur45
 209                          </paco>
 210                      </users>
 211                  </store>
 212                  <credential>
 213                      password_field   password
 214                      password_type   clear
 215                      class   Password
 216                  </credential>
 217              </members>
 218              <openid>
 219                  <ua_args>
 220                      whitelisted_hosts   127.0.0.1
 221                      whitelisted_hosts   localhost
 222                  </ua_args>
 223                  consumer_secret   Don't bother setting
 224                  ua_class   LWP::UserAgent
 225                  <credential>
 226                      <store>
 227                          class   OpenID
 228                      </store>
 229                      class   OpenID
 230                  </credential>
 231                  <extensions>
 232                      http://openid.net/extensions/sreg/1.1
 233                      required   email
 234                      optional   fullname,nickname,timezone
 235                  </extensions>
 236              </openid>
 237          </realms>
 238      </Plugin::Authentication>
 239
 240     And now, the same configuration in YAML. NB: YAML is whitespace
 241     sensitive.
 242
 243      name: MyApp
 244      Plugin::Authentication:
 245        default_realm: members
 246        realms:
 247          members:
 248            credential:
 249              class: Password
 250              password_field: password
 251              password_type: clear
 252            store:
 253              class: Minimal
 254              users:
 255                paco:
 256                  password: l4s4v3n7ur45
 257          openid:
 258            credential:
 259              class: OpenID
 260              store:
 261                class: OpenID
 262            consumer_secret: Don't bother setting
 263            ua_class: LWP::UserAgent
 264            ua_args:
 265              whitelisted_hosts:
 266                - 127.0.0.1
 267                - localhost
 268            extensions:
 269                - http://openid.net/extensions/sreg/1.1
 270                - required: email
 271                  optional: fullname,nickname,timezone
 272
 273     NB: There is no OpenID store yet.
 274
 275   EXTENSIONS TO OPENID
 276     The Simple Registration--<http://openid.net/extensions/sreg/1.1>--(SREG)
 277     extension to OpenID is supported in the Net::OpenID family now.
 278     Experimental support for it is included here as of v0.12. SREG is the
 279     only supported extension in OpenID 1.1. It's experimental in the sense
 280     it's a new interface and barely tested. Support for OpenID extensions is
 281     here to stay.
 282
 283   MORE ON CONFIGURATION
 284     These are set in your realm. See above.
 285
 286     ua_args and ua_class
 287         LWPx::ParanoidAgent is the default agent — "ua_class" — if it's
 288         available, LWP::UserAgent if not. You don't have to set it. I
 289         recommend that you do not override it. You can with any well behaved
 290         LWP::UserAgent. You probably should not. LWPx::ParanoidAgent buys
 291         you many defenses and extra security checks. When you allow your
 292         application users freedom to initiate external requests, you open an
 293         avenue for DoS (denial of service) attacks. LWPx::ParanoidAgent
 294         defends against this. LWP::UserAgent and any regular subclass of it
 295         will not.
 296
 297     consumer_secret
 298         The underlying Net::OpenID::Consumer object is seeded with a secret.
 299         If it's important to you to set your own, you can. The default uses
 300         this package name + its version + the sorted configuration keys of
 301         your Catalyst application (chopped at 255 characters if it's
 302         longer). This should generally be superior to any fixed string.
 303
 304 TODO
 305     Option to suppress fatals.
 306
 307     Support more of the new methods in the Net::OpenID kit.
 308
 309     There are some interesting implications with this sort of setup. Does a
 310     user aggregate realms or can a user be signed in under more than one
 311     realm? The documents could contain a recipe of the self-answering OpenID
 312     end-point that is in the tests.
 313
 314     Debug statements need to be both expanded and limited via realm
 315     configuration.
 316
 317     Better diagnostics in errors. Debug info at all consumer calls.
 318
 319     Roles from provider domains? Mapped? Direct? A generic "openid"
 320     auto_role?
 321
 322 THANKS
 323     To Benjamin Trott (Catalyst::Plugin::Authentication::OpenID), Tatsuhiko
 324     Miyagawa (Catalyst::Plugin::Authentication::Credential::OpenID), Brad
 325     Fitzpatrick for the great OpenID stuff, Martin Atkins for picking up the
 326     code to handle OpenID 2.0, and Jay Kuri and everyone else who has made
 327     Catalyst such a wonderful framework.
 328
 329     Menno Blom provided a bug fix and the hook to use OpenID extensions.
 330
 331 LICENSE AND COPYRIGHT
 332     Copyright (c) 2008-2009, Ashley Pond V "<ashley@cpan.org>". Some of
 333     Tatsuhiko Miyagawa's work is reused here.
 334
 335     This module is free software; you can redistribute it and modify it
 336     under the same terms as Perl itself. See perlartistic.
 337
 338 DISCLAIMER OF WARRANTY
 339     Because this software is licensed free of charge, there is no warranty
 340     for the software, to the extent permitted by applicable law. Except when
 341     otherwise stated in writing the copyright holders and other parties
 342     provide the software "as is" without warranty of any kind, either
 343     expressed or implied, including, but not limited to, the implied
 344     warranties of merchantability and fitness for a particular purpose. The
 345     entire risk as to the quality and performance of the software is with
 346     you. Should the software prove defective, you assume the cost of all
 347     necessary servicing, repair, or correction.
 348
 349     In no event unless required by applicable law or agreed to in writing
 350     will any copyright holder, or any other party who may modify or
 351     redistribute the software as permitted by the above license, be liable
 352     to you for damages, including any general, special, incidental, or
 353     consequential damages arising out of the use or inability to use the
 354     software (including but not limited to loss of data or data being
 355     rendered inaccurate or losses sustained by you or third parties or a
 356     failure of the software to operate with any other software), even if
 357     such holder or other party has been advised of the possibility of such
 358     damages.
 359
 360 SEE ALSO
 361     OpenID
 362         Net::OpenID::Server, Net::OpenID::VerifiedIdentity,
 363         Net::OpenID::Consumer, <http://openid.net/>,
 364         <http://openid.net/developers/specs/>, and
 365         <http://openid.net/extensions/sreg/1.1>.
 366
 367     Catalyst Authentication
 368         Catalyst, Catalyst::Plugin::Authentication,
 369         Catalyst::Manual::Tutorial::Authorization, and
 370         Catalyst::Manual::Tutorial::Authentication.
 371
 372     Catalyst Configuration
 373         Catalyst::Plugin::ConfigLoader, Config::General, and YAML.
 374
 375     Miscellaneous
 376         Catalyst::Manual::Tutorial, Template, LWPx::ParanoidAgent.
 377