lib/Catalyst/Authentication/Credential/OpenID.pm

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