lib/Catalyst/Authentication/Credential/OpenID.pm

   1 package Catalyst::Authentication::Credential::OpenID;
   2 use strict;
   3 # use warnings; no warnings "uninitialized"; # for testing, not production
   4 use parent "Class::Accessor::Fast";
   5
   6 BEGIN {
   7     __PACKAGE__->mk_accessors(qw/ _config realm debug secret /);
   8 }
   9
  10 our $VERSION = "0.15";
  11
  12 use Net::OpenID::Consumer;
  13 use Catalyst::Exception ();
  14
  15 sub new : method {
  16     my ( $class, $config, $c, $realm ) = @_;
  17     my $self = { _config => { %{ $config },
  18                               %{ $realm->{config} }
  19                           }
  20                  };
  21     bless $self, $class;
  22
  23     # 2.0 spec says "SHOULD" be named "openid_identifier."
  24     $self->_config->{openid_field} ||= "openid_identifier";
  25
  26     $self->debug( $self->_config->{debug} );
  27
  28     my $secret = $self->_config->{consumer_secret} ||= join("+",
  29                                                             __PACKAGE__,
  30                                                             $VERSION,
  31                                                             sort keys %{ $c->config }
  32                                                             );
  33
  34     $secret = substr($secret,0,255) if length $secret > 255;
  35     $self->secret($secret);
  36     # If user has no preference we prefer L::PA b/c it can prevent DoS attacks.
  37     $self->_config->{ua_class} ||= eval "use LWPx::ParanoidAgent" ?
  38         "LWPx::ParanoidAgent" : "LWP::UserAgent";
  39
  40     my $agent_class = $self->_config->{ua_class};
  41     eval "require $agent_class"
  42         or Catalyst::Exception->throw("Could not 'require' user agent class " .
  43                                       $self->_config->{ua_class});
  44
  45     $c->log->debug("Setting consumer secret: " . $secret) if $self->debug;
  46
  47     return $self;
  48 }
  49
  50 sub authenticate : method {
  51     my ( $self, $c, $realm, $authinfo ) = @_;
  52
  53     $c->log->debug("authenticate() called from " . $c->request->uri) if $self->debug;
  54
  55     my $field = $self->{_config}->{openid_field};
  56
  57     my $claimed_uri = $authinfo->{ $field };
  58
  59     # Its security related so we want to be explicit about GET/POST param retrieval.
  60     $claimed_uri ||= $c->req->method eq 'GET' ?
  61         $c->req->query_params->{ $field } : $c->req->body_params->{ $field };
  62
  63
  64     my $csr = Net::OpenID::Consumer->new(
  65         ua => $self->_config->{ua_class}->new(%{$self->_config->{ua_args} || {}}),
  66         args => $c->req->params,
  67         consumer_secret => $self->secret,
  68     );
  69
  70     if ( $self->_config->{extension_args} and $self->debug )
  71     {
  72         $c->log->info("The configuration key 'extension_args' is deprecated; use 'extensions'");
  73     }
  74
  75     my @extensions = $self->_config->{extensions} ?
  76         @{ $self->_config->{extensions} } : $self->_config->{extension_args} ?
  77         @{ $self->_config->{extension_args} } : ();
  78
  79     if ( $claimed_uri )
  80     {
  81         my $current = $c->uri_for($c->req->uri->path); # clear query/fragment...
  82
  83         my $identity = $csr->claimed_identity($claimed_uri);
  84         unless ( $identity )
  85         {
  86             if ( $self->_config->{errors_are_fatal} )
  87             {
  88                 Catalyst::Exception->throw($csr->err);
  89             }
  90             else
  91             {
  92                 $c->log->error($csr->err . " -- $claimed_uri");
  93                 $c->detach();
  94             }
  95         }
  96
  97         $identity->set_extension_args(@extensions)
  98             if @extensions;
  99
 100         my $check_url = $identity->check_url(
 101             return_to  => $current . '?openid-check=1',
 102             trust_root => $current,
 103             delayed_return => 1,
 104         );
 105         $c->res->redirect($check_url);
 106         $c->detach();
 107     }
 108     elsif ( $c->req->params->{'openid-check'} )
 109     {
 110         if ( my $setup_url = $csr->user_setup_url )
 111         {
 112             $c->res->redirect($setup_url);
 113             return;
 114         }
 115         elsif ( $csr->user_cancel )
 116         {
 117             return;
 118         }
 119         elsif ( my $identity = $csr->verified_identity )
 120         {
 121             # This is where we ought to build an OpenID user and verify against the spec.
 122             my $user = +{ map { $_ => scalar $identity->$_ }
 123                 qw( url display rss atom foaf declared_rss declared_atom declared_foaf foafmaker ) };
 124             # Dude, I did not design the array as hash spec. Don't curse me [apv].
 125             my %flat = @extensions;
 126             for my $key ( keys %flat )
 127             {
 128                 $user->{extensions}->{$key} = $identity->signed_extension_fields($key);
 129             }
 130
 131             my $user_obj = $realm->find_user($user, $c);
 132
 133             if ( ref $user_obj )
 134             {
 135                 return $user_obj;
 136             }
 137             else
 138             {
 139                 $c->log->debug("Verified OpenID identity failed to load with find_user; bad user_class? Try 'Null.'") if $self->debug;
 140                 return;
 141             }
 142         }
 143         else
 144         {
 145             $self->_config->{errors_are_fatal} ?
 146                 Catalyst::Exception->throw("Error validating identity: " . $csr->err)
 147                       :
 148                 $c->log->error( $csr->err);
 149         }
 150     }
 151     return;
 152 }
 153
 154 1;
 155
 156 __END__
 157
 158 =head1 NAME
 159
 160 Catalyst::Authentication::Credential::OpenID - OpenID credential for Catalyst::Plugin::Authentication framework.
 161
 162 =head1 VERSION
 163
 164 0.15
 165
 166 =head1 BACKWARDS COMPATIBILITY CHANGES
 167
 168 =head2 EXTENSION_ARGS v EXTENSIONS
 169
 170 B<NB>: The extensions were previously configured under the key C<extension_args>. They are now configured under C<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.
 171
 172 As previously noted, L</EXTENSIONS TO OPENID>, I have not tested the extensions. I would be grateful for any feedback or, better, tests.
 173
 174 =head2 FATALS
 175
 176 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 C<errors_are_fatal> to a true value.
 177
 178 =head1 SYNOPSIS
 179
 180 In MyApp.pm-
 181
 182  use Catalyst qw/
 183     Authentication
 184     Session
 185     Session::Store::FastMmap
 186     Session::State::Cookie
 187  /;
 188
 189 Somewhere in myapp.conf-
 190
 191  <Plugin::Authentication>
 192      default_realm   openid
 193      <realms>
 194          <openid>
 195              <credential>
 196                  class   OpenID
 197                  ua_class   LWP::UserAgent
 198              </credential>
 199          </openid>
 200      </realms>
 201  </Plugin::Authentication>
 202
 203 Or in your myapp.yml if you're using L<YAML> instead-
 204
 205  Plugin::Authentication:
 206    default_realm: openid
 207    realms:
 208      openid:
 209        credential:
 210          class: OpenID
 211          ua_class: LWP::UserAgent
 212
 213 In a controller, perhaps C<Root::openid>-
 214
 215  sub openid : Local {
 216       my($self, $c) = @_;
 217
 218       if ( $c->authenticate() )
 219       {
 220           $c->flash(message => "You signed in with OpenID!");
 221           $c->res->redirect( $c->uri_for('/') );
 222       }
 223       else
 224       {
 225           # Present OpenID form.
 226       }
 227  }
 228
 229 And a L<Template> to match in C<openid.tt>-
 230
 231  <form action="[% c.uri_for('/openid') %]" method="GET" name="openid">
 232  <input type="text" name="openid_identifier" class="openid" />
 233  <input type="submit" value="Sign in with OpenID" />
 234  </form>
 235
 236 =head1 DESCRIPTION
 237
 238 This is the B<third> OpenID related authentication piece for
 239 L<Catalyst>. The first E<mdash> L<Catalyst::Plugin::Authentication::OpenID>
 240 by Benjamin Trott E<mdash> was deprecated by the second E<mdash>
 241 L<Catalyst::Plugin::Authentication::Credential::OpenID> by Tatsuhiko
 242 Miyagawa E<mdash> and this is an attempt to deprecate both by conforming to
 243 the newish, at the time of this module's inception, realm-based
 244 authentication in L<Catalyst::Plugin::Authentication>.
 245
 246  1. Catalyst::Plugin::Authentication::OpenID
 247  2. Catalyst::Plugin::Authentication::Credential::OpenID
 248  3. Catalyst::Authentication::Credential::OpenID
 249
 250 The benefit of this version is that you can use an arbitrary number of
 251 authentication systems in your L<Catalyst> application and configure
 252 and call all of them in the same way.
 253
 254 Note that both earlier versions of OpenID authentication use the method
 255 C<authenticate_openid()>. This module uses C<authenticate()> and
 256 relies on you to specify the realm. You can specify the realm as the
 257 default in the configuration or inline with each
 258 C<authenticate()> call; more below.
 259
 260 This module functions quite differently internally from the others.
 261 See L<Catalyst::Plugin::Authentication::Internals> for more about this
 262 implementation.
 263
 264 =head1 METHODS
 265
 266 =over 4
 267
 268 =item $c->authenticate({},"your_openid_realm");
 269
 270 Call to authenticate the user via OpenID. Returns false if
 271 authorization is unsuccessful. Sets the user into the session and
 272 returns the user object if authentication succeeds.
 273
 274 You can see in the call above that the authentication hash is empty.
 275 The implicit OpenID parameter is, as the 2.0 specification says it
 276 SHOULD be, B<openid_identifier>. You can set it anything you like in
 277 your realm configuration, though, under the key C<openid_field>. If
 278 you call C<authenticate()> with the empty info hash and no configured
 279 C<openid_field> then only C<openid_identifier> is checked.
 280
 281 It implicitly does this (sort of, it checks the request method too)-
 282
 283  my $claimed_uri = $c->req->params->{openid_identifier};
 284  $c->authenticate({openid_identifier => $claimed_uri});
 285
 286 =item Catalyst::Authentication::Credential::OpenID->new()
 287
 288 You will never call this. Catalyst does it for you. The only important
 289 thing you might like to know about it is that it merges its realm
 290 configuration with its configuration proper. If this doesn't mean
 291 anything to you, don't worry.
 292
 293 =back
 294
 295 =head2 USER METHODS
 296
 297 Currently the only supported user class is L<Catalyst::Plugin::Authentication::User::Hash>.
 298
 299 =over 4
 300
 301 =item $c->user->url
 302
 303 =item $c->user->display
 304
 305 =item $c->user->rss
 306
 307 =item $c->user->atom
 308
 309 =item $c->user->foaf
 310
 311 =item $c->user->declared_rss
 312
 313 =item $c->user->declared_atom
 314
 315 =item $c->user->declared_foaf
 316
 317 =item $c->user->foafmaker
 318
 319 =back
 320
 321 See L<Net::OpenID::VerifiedIdentity> for details.
 322
 323 =head1 CONFIGURATION
 324
 325 Catalyst authentication is now configured entirely from your
 326 application's configuration. Do not, for example, put
 327 C<Credential::OpenID> into your C<use Catalyst ...> statement.
 328 Instead, tell your application that in one of your authentication
 329 realms you will use the credential.
 330
 331 In your application the following will give you two different
 332 authentication realms. One called "members" which authenticates with
 333 clear text passwords and one called "openid" which uses... uh, OpenID.
 334
 335  __PACKAGE__->config
 336     ( name => "MyApp",
 337       "Plugin::Authentication" => {
 338           default_realm => "members",
 339           realms => {
 340               members => {
 341                   credential => {
 342                       class => "Password",
 343                       password_field => "password",
 344                       password_type => "clear"
 345                       },
 346                           store => {
 347                               class => "Minimal",
 348                               users => {
 349                                   paco => {
 350                                       password => "l4s4v3n7ur45",
 351                                   },
 352                               }
 353                           }
 354               },
 355               openid => {
 356                   credential => {
 357                       class => "OpenID",
 358                       store => {
 359                           class => "OpenID",
 360                       },
 361                       consumer_secret => "Don't bother setting",
 362                       ua_class => "LWP::UserAgent",
 363                       # whitelist is only relevant for LWPx::ParanoidAgent
 364                       ua_args => {
 365                           whitelisted_hosts => [qw/ 127.0.0.1 localhost /],
 366                       },
 367                       extensions => [
 368                           'http://openid.net/extensions/sreg/1.1',
 369                           {
 370                            required => 'email',
 371                            optional => 'fullname,nickname,timezone',
 372                           },
 373                       ],
 374                   },
 375               },
 376           },
 377       }
 378     );
 379
 380 This is the same configuration in the default L<Catalyst> configuration format from L<Config::General>.
 381
 382  name   MyApp
 383  <Plugin::Authentication>
 384      default_realm   members
 385      <realms>
 386          <members>
 387              <store>
 388                  class   Minimal
 389                  <users>
 390                      <paco>
 391                          password   l4s4v3n7ur45
 392                      </paco>
 393                  </users>
 394              </store>
 395              <credential>
 396                  password_field   password
 397                  password_type   clear
 398                  class   Password
 399              </credential>
 400          </members>
 401          <openid>
 402              <credential>
 403                  <store>
 404                      class   OpenID
 405                  </store>
 406                  class   OpenID
 407                  <ua_args>
 408                      whitelisted_hosts   127.0.0.1
 409                      whitelisted_hosts   localhost
 410                  </ua_args>
 411                  consumer_secret   Don't bother setting
 412                  ua_class   LWP::UserAgent
 413                  <extensions>
 414                      http://openid.net/extensions/sreg/1.1
 415                      required   email
 416                      optional   fullname,nickname,timezone
 417                  </extensions>
 418              </credential>
 419          </openid>
 420      </realms>
 421  </Plugin::Authentication>
 422
 423 And now, the same configuration in L<YAML>. B<NB>: L<YAML> is whitespace sensitive.
 424
 425  name: MyApp
 426  Plugin::Authentication:
 427    default_realm: members
 428    realms:
 429      members:
 430        credential:
 431          class: Password
 432          password_field: password
 433          password_type: clear
 434        store:
 435          class: Minimal
 436          users:
 437            paco:
 438              password: l4s4v3n7ur45
 439      openid:
 440        credential:
 441          class: OpenID
 442          store:
 443            class: OpenID
 444          consumer_secret: Don't bother setting
 445          ua_class: LWP::UserAgent
 446          ua_args:
 447            # whitelist is only relevant for LWPx::ParanoidAgent
 448            whitelisted_hosts:
 449              - 127.0.0.1
 450              - localhost
 451          extensions:
 452              - http://openid.net/extensions/sreg/1.1
 453              - required: email
 454                optional: fullname,nickname,timezone
 455
 456 B<NB>: There is no OpenID store yet.
 457
 458 =head2 EXTENSIONS TO OPENID
 459
 460 The Simple Registration--L<http://openid.net/extensions/sreg/1.1>--(SREG) extension to OpenID is supported in the L<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.
 461
 462 =head2 MORE ON CONFIGURATION
 463
 464 =over
 465
 466 =item ua_args and ua_class
 467
 468 L<LWPx::ParanoidAgent> is the default agent E<mdash> C<ua_class> E<mdash> if it's available, L<LWP::UserAgent> if not. You don't have to set
 469 it. I recommend that you do B<not> override it. You can with any well behaved L<LWP::UserAgent>. You probably should not.
 470 L<LWPx::ParanoidAgent> buys you many defenses and extra security checks. When you allow your application users freedom to initiate external
 471 requests, you open an avenue for DoS (denial of service) attacks. L<LWPx::ParanoidAgent> defends against this. L<LWP::UserAgent> and any
 472 regular subclass of it will not.
 473
 474 =item consumer_secret
 475
 476 The underlying L<Net::OpenID::Consumer> object is seeded with a secret. If it's important to you to set your own, you can. The default uses
 477 this package name + its version + the sorted configuration keys of your Catalyst application (chopped at 255 characters if it's longer).
 478 This should generally be superior to any fixed string.
 479
 480 =back
 481
 482 =head1 TODO
 483
 484 Option to suppress fatals.
 485
 486 Support more of the new methods in the L<Net::OpenID> kit.
 487
 488 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
 489 realm? The documents could contain a recipe of the self-answering OpenID end-point that is in the tests.
 490
 491 Debug statements need to be both expanded and limited via realm configuration.
 492
 493 Better diagnostics in errors. Debug info at all consumer calls.
 494
 495 Roles from provider domains? Mapped? Direct? A generic "openid" auto_role?
 496
 497 =head1 THANKS
 498
 499 To Benjamin Trott (L<Catalyst::Plugin::Authentication::OpenID>), Tatsuhiko Miyagawa (L<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.
 500
 501 Menno Blom provided a bug fix and the hook to use OpenID extensions.
 502
 503 =head1 LICENSE AND COPYRIGHT
 504
 505 Copyright (c) 2008-2009, Ashley Pond V C<< <ashley@cpan.org> >>. Some of Tatsuhiko Miyagawa's work is reused here.
 506
 507 This module is free software; you can redistribute it and modify it under the same terms as Perl itself. See L<perlartistic>.
 508
 509 =head1 DISCLAIMER OF WARRANTY
 510
 511 Because this software is licensed free of charge, there is no warranty for the software, to the extent permitted by applicable law. Except
 512 when otherwise stated in writing the copyright holders and other parties provide the software "as is" without warranty of any kind, either
 513 expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The
 514 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
 515 necessary servicing, repair, or correction.
 516
 517 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
 518 redistribute the software as permitted by the above license, be liable to you for damages, including any general, special, incidental, or
 519 consequential damages arising out of the use or inability to use the software (including but not limited to loss of data or data being
 520 rendered inaccurate or losses sustained by you or third parties or a failure of the software to operate with any other software), even if
 521 such holder or other party has been advised of the possibility of such damages.
 522
 523 =head1 SEE ALSO
 524
 525 =over 4
 526
 527 =item OpenID
 528
 529 L<Net::OpenID::Server>, L<Net::OpenID::VerifiedIdentity>, L<Net::OpenID::Consumer>, L<http://openid.net/>,
 530 L<http://openid.net/developers/specs/>, and L<http://openid.net/extensions/sreg/1.1>.
 531
 532 =item Catalyst Authentication
 533
 534 L<Catalyst>, L<Catalyst::Plugin::Authentication>, L<Catalyst::Manual::Tutorial::Authorization>, and
 535 L<Catalyst::Manual::Tutorial::Authentication>.
 536
 537 =item Catalyst Configuration
 538
 539 L<Catalyst::Plugin::ConfigLoader>, L<Config::General>, and L<YAML>.
 540
 541 =item Miscellaneous
 542
 543 L<Catalyst::Manual::Tutorial>, L<Template>, L<LWPx::ParanoidAgent>.
 544
 545 =back
 546
 547 =cut