NAME

BACKWARDS COMPATIBILITY CHANGES

SYNOPSIS

 use Catalyst qw/
    Authentication
    Session
    Session::Store::FastMmap
    Session::State::Cookie
 /;

Somewhere in myapp.conf-

 <Plugin::Authentication>
     default_realm   openid
     <realms>
         <openid>
             <credential>
                 class   OpenID
                 ua_class   LWP::UserAgent
             </credential>
         </openid>
     </realms>
 </Plugin::Authentication>

Or in your myapp.yml if you're using YAML instead-

 Plugin::Authentication:
   default_realm: openid
   realms:
     openid:
       credential:
         class: OpenID
         ua_class: LWP::UserAgent

In a controller, perhaps "Root::openid"-

 sub openid : Local {
      my($self, $c) = @_;

      if ( $c->authenticate() )
      {
          $c->flash(message => "You signed in with OpenID!");
          $c->res->redirect( $c->uri_for('/') );
      }
      else
      {
          # Present OpenID form.
      }
 }

And a Template to match in "openid.tt"-

 <form action="[% c.uri_for('/openid') %]" method="GET" name="openid">
 <input type="text" name="openid_identifier" class="openid" />
 <input type="submit" value="Sign in with OpenID" />
 </form>

DESCRIPTION

 1. Catalyst::Plugin::Authentication::OpenID
 2. Catalyst::Plugin::Authentication::Credential::OpenID
 3. Catalyst::Authentication::Credential::OpenID

The benefit of this version is that you can use an arbitrary number of authentication systems in your Catalyst application and configure and call all of them in the same way.

Note that both earlier versions of OpenID authentication use the method "authenticate_openid()". This module uses "authenticate()" and relies on you to specify the realm. You can specify the realm as the default in the configuration or inline with each "authenticate()" call; more below.

This module functions quite differently internally from the others. See Catalyst::Plugin::Authentication::Internals for more about this implementation.

METHODS

$c->authenticate({},"your_openid_realm");

Call to authenticate the user via OpenID. Returns false if authorization is unsuccessful. Sets the user into the session and returns the user object if authentication succeeds.

You can see in the call above that the authentication hash is empty. The implicit OpenID parameter is, as the 2.0 specification says it SHOULD be, openid_identifier. You can set it anything you like in your realm configuration, though, under the key "openid_field". If you call "authenticate()" with the empty info hash and no configured "openid_field" then only "openid_identifier" is checked.

It implicitly does this (sort of, it checks the request method too)-

 my $claimed_uri = $c->req->params->{openid_identifier};
 $c->authenticate({openid_identifier => $claimed_uri});
    

Catalyst::Authentication::Credential::OpenID->new()

You will never call this. Catalyst does it for you. The only important thing you might like to know about it is that it merges its realm configuration with its configuration proper. If this doesn't mean anything to you, don't worry.

CONFIGURATION

In your application the following will give you two different authentication realms. One called "members" which authenticates with clear text passwords and one called "openid" which uses... uh, OpenID.

 __PACKAGE__->config
    ( name => "MyApp",
      "Plugin::Authentication" => {
          default_realm => "members",
          realms => {
              members => {
                  credential => {
                      class => "Password",
                      password_field => "password",
                      password_type => "clear"
                      },
                          store => {
                              class => "Minimal",
                              users => {
                                  paco => {
                                      password => "l4s4v3n7ur45",
                                  },
                              }
                          }
              },
              openid => {
                  credential => {
                      class => "OpenID",
                      store => {
                          class => "OpenID",
                      },
                      consumer_secret => "Don't bother setting",
                      ua_class => "LWP::UserAgent",
                      # whitelist is only relevant for LWPx::ParanoidAgent
                      ua_args => {
                          whitelisted_hosts => [qw/ 127.0.0.1 localhost /],
                      },
                      extensions => [
                          'http://openid.net/extensions/sreg/1.1',
                          {
                           required => 'email',
                           optional => 'fullname,nickname,timezone',
                          },
                      ],
                  },
              },
          },
      }
    );

This is the same configuration in the default Catalyst configuration format from Config::General.

 name   MyApp
 <Plugin::Authentication>
     default_realm   members
     <realms>
         <members>
             <store>
                 class   Minimal
                 <users>
                     <paco>
                         password   l4s4v3n7ur45
                     </paco>
                 </users>
             </store>
             <credential>
                 password_field   password
                 password_type   clear
                 class   Password
             </credential>
         </members>
         <openid>
             <credential>
                 <store>
                     class   OpenID
                 </store>
                 class   OpenID
                 <ua_args>
                     whitelisted_hosts   127.0.0.1
                     whitelisted_hosts   localhost
                 </ua_args>
                 consumer_secret   Don't bother setting
                 ua_class   LWP::UserAgent
                 <extensions>
                     http://openid.net/extensions/sreg/1.1
                     required   email
                     optional   fullname,nickname,timezone
                 </extensions>
             </credential>
         </openid>
     </realms>
 </Plugin::Authentication>

And now, the same configuration in YAML. NB: YAML is whitespace sensitive.

 name: MyApp
 Plugin::Authentication:
   default_realm: members
   realms:
     members:
       credential:
         class: Password
         password_field: password
         password_type: clear
       store:
         class: Minimal
         users:
           paco:
             password: l4s4v3n7ur45
     openid:
       credential:
         class: OpenID
         store:
           class: OpenID
         consumer_secret: Don't bother setting
         ua_class: LWP::UserAgent
         ua_args:
           # whitelist is only relevant for LWPx::ParanoidAgent
           whitelisted_hosts:
             - 127.0.0.1
             - localhost
         extensions:
             - http://openid.net/extensions/sreg/1.1
             - required: email
               optional: fullname,nickname,timezone

NB: There is no OpenID store yet.

You can set "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.

 'Plugin::Authentication' => {
    openid => {
        credential => {
            class => 'OpenID',
            ua_class => 'LWP::UserAgent',
            extensions => {
                'http://openid.net/extensions/sreg/1.1' => {
                    required => 'nickname,email,fullname',
                    optional => 'timezone,language,dob,country,gender'
                },
                'http://openid.net/srv/ax/1.0' => {
                    mode => 'fetch_request',
                    'type.nickname' => 'http://axschema.org/namePerson/friendly',
                    'type.email' => 'http://axschema.org/contact/email',
                    'type.fullname' => 'http://axschema.org/namePerson',
                    'type.firstname' => 'http://axschema.org/namePerson/first',
                    'type.lastname' => 'http://axschema.org/namePerson/last',
                    'type.dob' => 'http://axschema.org/birthDate',
                    'type.gender' => 'http://axschema.org/person/gender',
                    'type.country' => 'http://axschema.org/contact/country/home',
                    'type.language' => 'http://axschema.org/pref/language',
                    'type.timezone' => 'http://axschema.org/pref/timezone',
                    required => 'nickname,fullname,email,firstname,lastname',
                    if_available => 'dob,gender,country,language,timezone',
            },
            },
        },
    },
    default_realm => 'openid',
 };

TODO

Support more of the new methods in the Net::OpenID kit.

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.

Debug statements need to be both expanded and limited via realm configuration.

Better diagnostics in errors. Debug info at all consumer calls.

Roles from provider domains? Mapped? Direct? A generic "openid" auto_role?

THANKS

Menno Blom provided a bug fix and the hook to use OpenID extensions.

LICENSE AND COPYRIGHT

This module is free software; you can redistribute it and modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

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 redistribute the software as permitted by the above license, be liable to you for damages, including any general, special, incidental, or consequential damages arising out of the use or inability to use the software (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the software to operate with any other software), even if such holder or other party has been advised of the possibility of such damages.

SEE ALSO

OpenID

Net::OpenID::Server, Net::OpenID::VerifiedIdentity, Net::OpenID::Consumer, <http://openid.net/>, <http://openid.net/developers/specs/>, and <http://openid.net/extensions/sreg/1.1>.

Catalyst Authentication

Catalyst, Catalyst::Plugin::Authentication, Catalyst::Manual::Tutorial::Authorization, and Catalyst::Manual::Tutorial::Authentication.

Catalyst Configuration

Catalyst::Plugin::ConfigLoader, Config::General, and YAML.

Miscellaneous

Catalyst::Manual::Tutorial, Template, LWPx::ParanoidAgent.