Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Catalyst::AuthenticatiUserCContributedtPerltDoctication::Credential::OpenID(3)

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

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 a Catalyst::Plugin::Authentication::OpenID	by Benjamin Trott a
       was deprecated by the second a
       Catalyst::Plugin::Authentication::Credential::OpenID by Tatsuhiko
       Miyagawa	a 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 JAxndling	combining Sreg and Google's
       extenstionsa

	'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 a "ua_class" a 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.

perl v5.24.1		       Catalyst::Authentication::Credential::OpenID(3)

NAME | BACKWARDS COMPATIBILITY CHANGES | SYNOPSIS | DESCRIPTION | METHODS | CONFIGURATION | TODO | THANKS | LICENSE AND COPYRIGHT | DISCLAIMER OF WARRANTY | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Catalyst::Authentication::Credential::OpenID&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help