NAME
    Catalyst::Authentication::Credential::OpenID - OpenID credential for
    Catalyst::Plugin::Authentication framework.

VERSION
    0.16_01

BACKWARDS COMPATIBILITY CHANGES
  EXTENSION_ARGS v EXTENSIONS
    NB: The extensions were previously configured under the key
    "extension_args". They are now configured under "extensions".
    "extension_args" is no longer honored.

    As previously noted, "EXTENSIONS TO OPENID", I have not tested the
    extensions. I would be grateful for any feedback or, better, tests.

  FATALS
    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 "errors_are_fatal" to a true value.

SYNOPSIS
    In MyApp.pm-

     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
    This is the third OpenID related authentication piece for Catalyst. The
    first — Catalyst::Plugin::Authentication::OpenID by Benjamin Trott — was
    deprecated by the second —
    Catalyst::Plugin::Authentication::Credential::OpenID by Tatsuhiko
    Miyagawa — and this is an attempt to deprecate both by conforming to the
    newish, at the time of this module's inception, realm-based
    authentication in Catalyst::Plugin::Authentication.

     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.

  USER METHODS
    Currently the only supported user class is
    Catalyst::Plugin::Authentication::User::Hash.

    $c->user->url
    $c->user->display
    $c->user->rss
    $c->user->atom
    $c->user->foaf
    $c->user->declared_rss
    $c->user->declared_atom
    $c->user->declared_foaf
    $c->user->foafmaker

    See Net::OpenID::VerifiedIdentity for details.

CONFIGURATION
    Catalyst authentication is now configured entirely from your
    application's configuration. Do not, for example, put
    "Credential::OpenID" into your "use Catalyst ..." statement. Instead,
    tell your application that in one of your authentication realms you will
    use the credential.

    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.

  EXTENSIONS TO OPENID
    The Simple Registration--<http://openid.net/extensions/sreg/1.1>--(SREG)
    extension to OpenID is supported in the 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.

    Google's OpenID is also now supported. Uh, I think.

    Here is a snippet from Thorben Jändling combining Sreg and Google's
    extenstions–

     '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',
     };

  MORE ON CONFIGURATION
    ua_args and ua_class
        LWPx::ParanoidAgent is the default agent — "ua_class" — if it's
        available, LWP::UserAgent if not. You don't have to set it. I
        recommend that you do not override it. You can with any well behaved
        LWP::UserAgent. You probably should not. 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. LWPx::ParanoidAgent
        defends against this. LWP::UserAgent and any regular subclass of it
        will not.

    consumer_secret
        The underlying 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.

TODO
    Option to suppress fatals.

    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
    To Benjamin Trott (Catalyst::Plugin::Authentication::OpenID), Tatsuhiko
    Miyagawa (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.

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

LICENSE AND COPYRIGHT
    Copyright (c) 2008-2009, Ashley Pond V "<ashley@cpan.org>". Some of
    Tatsuhiko Miyagawa's work is reused here.

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

DISCLAIMER OF WARRANTY
    Because this software is licensed free of charge, there is no warranty
    for the software, to the extent permitted by applicable law. Except when
    otherwise stated in writing the copyright holders and other parties
    provide the software "as is" without warranty of any kind, either
    expressed or implied, including, but not limited to, the implied
    warranties of merchantability and fitness for a particular purpose. The
    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
    necessary servicing, repair, or correction.

    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.

