lib/Catalyst/Authentication/Credential/OpenID.pm

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