[catagits/Catalyst-Authentication-Credential-OpenID.git] / README

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

VERSION
    0.14_02

BACKWARDS COMPATIBILITY CHANGE
    NB: The extenstions were previously configured under the key
    "extension_args". They are now configured under "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.

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

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
                 </credential>
                 ua_class   LWP::UserAgent
             </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 => {
                      consumer_secret => "Don't bother setting",
                      ua_class => "LWP::UserAgent",
                      ua_args => {
                          whitelisted_hosts => [qw/ 127.0.0.1 localhost /],
                      },
                      credential => {
                          class => "OpenID",
                          store => {
                              class => "OpenID",
                          },
                      },
                      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>
                 <ua_args>
                     whitelisted_hosts   127.0.0.1
                     whitelisted_hosts   localhost
                 </ua_args>
                 consumer_secret   Don't bother setting
                 ua_class   LWP::UserAgent
                 <credential>
                     <store>
                         class   OpenID
                     </store>
                     class   OpenID
                 </credential>
                 <extensions>
                     http://openid.net/extensions/sreg/1.1
                     required   email
                     optional   fullname,nickname,timezone
                 </extensions>
             </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:
             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.

  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.

  MORE ON CONFIGURATION
    These are set in your realm. See above.

    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.
Commit	Line	Data
5bd16806	1	NAME
	2	Catalyst::Authentication::Credential::OpenID - OpenID credential for
	3	Catalyst::Plugin::Authentication framework.
e5b6823d	4
5bd16806	5	VERSION
5bd16806	6	0.14_02
e5b6823d	7
5bd16806	8	BACKWARDS COMPATIBILITY CHANGE
	9	NB: The extenstions were previously configured under the key
	10	"extension_args". They are now configured under "extensions". This
	11	prevents the need for double configuration but it breaks extensions in
	12	your application if you do not change the name. The old version is
	13	supported for now but may be phased out at any time.
e5b6823d	14
5bd16806	15	As previously noted, "EXTENSIONS TO OPENID", I have not tested the
5bd16806	16	extensions. I would be grateful for any feedback or, better, tests.
e5b6823d	17
5bd16806	18	SYNOPSIS
5bd16806	19	In MyApp.pm-
e5b6823d	20
5bd16806	21	use Catalyst qw/
	22	Authentication
	23	Session
	24	Session::Store::FastMmap
	25	Session::State::Cookie
	26	/;
e5b6823d	27
5bd16806	28	Somewhere in myapp.conf-
788804c2	29
5bd16806	30	<Plugin::Authentication>
	31	default_realm openid
	32	<realms>
	33	<openid>
	34	<credential>
	35	class OpenID
	36	</credential>
	37	ua_class LWP::UserAgent
	38	</openid>
	39	</realms>
	40	</Plugin::Authentication>
788804c2	41
5bd16806	42	Or in your myapp.yml if you're using YAML instead-
788804c2	43
5bd16806	44	Plugin::Authentication:
	45	default_realm: openid
	46	realms:
	47	openid:
	48	credential:
	49	class: OpenID
	50	ua_class: LWP::UserAgent
788804c2	51
5bd16806	52	In a controller, perhaps "Root::openid"-
788804c2	53
5bd16806	54	sub openid : Local {
	55	my($self, $c) = @_;
	56
	57	if ( $c->authenticate() )
	58	{
	59	$c->flash(message => "You signed in with OpenID!");
	60	$c->res->redirect( $c->uri_for('/') );
	61	}
	62	else
	63	{
	64	# Present OpenID form.
	65	}
	66	}
	67
	68	And a Template to match in "openid.tt"-
	69
	70	<form action="[% c.uri_for('/openid') %]" method="GET" name="openid">
	71	<input type="text" name="openid_identifier" class="openid" />
	72	<input type="submit" value="Sign in with OpenID" />
	73	</form>
	74
	75	DESCRIPTION
	76	This is the third OpenID related authentication piece for Catalyst. The
	77	first — Catalyst::Plugin::Authentication::OpenID by Benjamin Trott — was
	78	deprecated by the second —
	79	Catalyst::Plugin::Authentication::Credential::OpenID by Tatsuhiko
	80	Miyagawa — and this is an attempt to deprecate both by conforming to the
	81	newish, at the time of this module's inception, realm-based
	82	authentication in Catalyst::Plugin::Authentication.
	83
	84	1. Catalyst::Plugin::Authentication::OpenID
	85	2. Catalyst::Plugin::Authentication::Credential::OpenID
	86	3. Catalyst::Authentication::Credential::OpenID
	87
	88	The benefit of this version is that you can use an arbitrary number of
	89	authentication systems in your Catalyst application and configure and
	90	call all of them in the same way.
	91
	92	Note that both earlier versions of OpenID authentication use the method
	93	"authenticate_openid()". This module uses "authenticate()" and relies on
	94	you to specify the realm. You can specify the realm as the default in
	95	the configuration or inline with each "authenticate()" call; more below.
	96
	97	This module functions quite differently internally from the others. See
	98	Catalyst::Plugin::Authentication::Internals for more about this
	99	implementation.
	100
	101	METHODS
	102	$c->authenticate({},"your_openid_realm");
	103	Call to authenticate the user via OpenID. Returns false if
	104	authorization is unsuccessful. Sets the user into the session and
	105	returns the user object if authentication succeeds.
	106
	107	You can see in the call above that the authentication hash is empty.
	108	The implicit OpenID parameter is, as the 2.0 specification says it
	109	SHOULD be, openid_identifier. You can set it anything you like in
	110	your realm configuration, though, under the key "openid_field". If
	111	you call "authenticate()" with the empty info hash and no configured
	112	"openid_field" then only "openid_identifier" is checked.
	113
	114	It implicitly does this (sort of, it checks the request method too)-
	115
	116	my $claimed_uri = $c->req->params->{openid_identifier};
	117	$c->authenticate({openid_identifier => $claimed_uri});
118
119	Catalyst::Authentication::Credential::OpenID->new()
120	You will never call this. Catalyst does it for you. The only
121	important thing you might like to know about it is that it merges
122	its realm configuration with its configuration proper. If this
123	doesn't mean anything to you, don't worry.
124
125	USER METHODS
126	Currently the only supported user class is
127	Catalyst::Plugin::Authentication::User::Hash.
128
129	$c->user->url
130	$c->user->display
131	$c->user->rss
132	$c->user->atom
133	$c->user->foaf
134	$c->user->declared_rss
135	$c->user->declared_atom
136	$c->user->declared_foaf
137	$c->user->foafmaker
138
139	See Net::OpenID::VerifiedIdentity for details.
140
141	CONFIGURATION
142	Catalyst authentication is now configured entirely from your
143	application's configuration. Do not, for example, put
144	"Credential::OpenID" into your "use Catalyst ..." statement. Instead,
145	tell your application that in one of your authentication realms you will
146	use the credential.
147
148	In your application the following will give you two different
149	authentication realms. One called "members" which authenticates with
150	clear text passwords and one called "openid" which uses... uh, OpenID.
151
152	__PACKAGE__->config
153	( name => "MyApp",
154	"Plugin::Authentication" => {
155	default_realm => "members",
156	realms => {
157	members => {
158	credential => {
159	class => "Password",
160	password_field => "password",
161	password_type => "clear"
162	},
163	store => {
164	class => "Minimal",
165	users => {
166	paco => {
167	password => "l4s4v3n7ur45",
168	},
169	}
170	}
171	},
172	openid => {
173	consumer_secret => "Don't bother setting",
174	ua_class => "LWP::UserAgent",
175	ua_args => {
176	whitelisted_hosts => [qw/ 127.0.0.1 localhost /],
177	},
178	credential => {
179	class => "OpenID",
180	store => {
181	class => "OpenID",
182	},
183	},
184	extensions => [
185	'http://openid.net/extensions/sreg/1.1',
186	{
187	required => 'email',
188	optional => 'fullname,nickname,timezone',
189	},
190	],
191	},
192	},
193	}
194	);
195
196	This is the same configuration in the default Catalyst configuration
197	format from Config::General.
198
199	name MyApp
200	<Plugin::Authentication>
201	default_realm members
202	<realms>
203	<members>
204	<store>
205	class Minimal
206	<users>
207	<paco>
208	password l4s4v3n7ur45
209	</paco>
210	</users>
211	</store>
212	<credential>
213	password_field password
214	password_type clear
215	class Password
216	</credential>
217	</members>
218	<openid>
219	<ua_args>
220	whitelisted_hosts 127.0.0.1
221	whitelisted_hosts localhost
222	</ua_args>
223	consumer_secret Don't bother setting
224	ua_class LWP::UserAgent
225	<credential>
226	<store>
227	class OpenID
228	</store>
229	class OpenID
230	</credential>
231	<extensions>
232	http://openid.net/extensions/sreg/1.1
233	required email
234	optional fullname,nickname,timezone
235	</extensions>
236	</openid>
237	</realms>
238	</Plugin::Authentication>
239
240	And now, the same configuration in YAML. NB: YAML is whitespace
241	sensitive.
242
243	name: MyApp
244	Plugin::Authentication:
245	default_realm: members
246	realms:
247	members:
248	credential:
249	class: Password
250	password_field: password
251	password_type: clear
252	store:
253	class: Minimal
254	users:
255	paco:
256	password: l4s4v3n7ur45
257	openid:
258	credential:
259	class: OpenID
260	store:
261	class: OpenID
262	consumer_secret: Don't bother setting
263	ua_class: LWP::UserAgent
264	ua_args:
265	whitelisted_hosts:
266	- 127.0.0.1
267	- localhost
268	extensions:
269	- http://openid.net/extensions/sreg/1.1
270	- required: email
271	optional: fullname,nickname,timezone
272
273	NB: There is no OpenID store yet.
274
275	EXTENSIONS TO OPENID
276	The Simple Registration--<http://openid.net/extensions/sreg/1.1>--(SREG)
277	extension to OpenID is supported in the Net::OpenID family now.
278	Experimental support for it is included here as of v0.12. SREG is the
279	only supported extension in OpenID 1.1. It's experimental in the sense
280	it's a new interface and barely tested. Support for OpenID extensions is
281	here to stay.
282
283	MORE ON CONFIGURATION
284	These are set in your realm. See above.
285
286	ua_args and ua_class
287	LWPx::ParanoidAgent is the default agent — "ua_class" — if it's
288	available, LWP::UserAgent if not. You don't have to set it. I
289	recommend that you do not override it. You can with any well behaved
290	LWP::UserAgent. You probably should not. LWPx::ParanoidAgent buys
291	you many defenses and extra security checks. When you allow your
292	application users freedom to initiate external requests, you open an
293	avenue for DoS (denial of service) attacks. LWPx::ParanoidAgent
294	defends against this. LWP::UserAgent and any regular subclass of it
295	will not.
296
297	consumer_secret
298	The underlying Net::OpenID::Consumer object is seeded with a secret.
299	If it's important to you to set your own, you can. The default uses
300	this package name + its version + the sorted configuration keys of
301	your Catalyst application (chopped at 255 characters if it's
302	longer). This should generally be superior to any fixed string.
303
304	TODO
305	Option to suppress fatals.
306
307	Support more of the new methods in the Net::OpenID kit.
308
309	There are some interesting implications with this sort of setup. Does a
310	user aggregate realms or can a user be signed in under more than one
311	realm? The documents could contain a recipe of the self-answering OpenID
312	end-point that is in the tests.
313
314	Debug statements need to be both expanded and limited via realm
315	configuration.
316
317	Better diagnostics in errors. Debug info at all consumer calls.
318
319	Roles from provider domains? Mapped? Direct? A generic "openid"
320	auto_role?
321
322	THANKS
323	To Benjamin Trott (Catalyst::Plugin::Authentication::OpenID), Tatsuhiko
324	Miyagawa (Catalyst::Plugin::Authentication::Credential::OpenID), Brad
325	Fitzpatrick for the great OpenID stuff, Martin Atkins for picking up the
326	code to handle OpenID 2.0, and Jay Kuri and everyone else who has made
327	Catalyst such a wonderful framework.
328
329	Menno Blom provided a bug fix and the hook to use OpenID extensions.
330
331	LICENSE AND COPYRIGHT
332	Copyright (c) 2008-2009, Ashley Pond V "<ashley@cpan.org>". Some of
333	Tatsuhiko Miyagawa's work is reused here.
334
335	This module is free software; you can redistribute it and modify it
336	under the same terms as Perl itself. See perlartistic.
337
338	DISCLAIMER OF WARRANTY
339	Because this software is licensed free of charge, there is no warranty
340	for the software, to the extent permitted by applicable law. Except when
341	otherwise stated in writing the copyright holders and other parties
342	provide the software "as is" without warranty of any kind, either
343	expressed or implied, including, but not limited to, the implied
344	warranties of merchantability and fitness for a particular purpose. The
345	entire risk as to the quality and performance of the software is with
346	you. Should the software prove defective, you assume the cost of all
347	necessary servicing, repair, or correction.
348
349	In no event unless required by applicable law or agreed to in writing
350	will any copyright holder, or any other party who may modify or
351	redistribute the software as permitted by the above license, be liable
352	to you for damages, including any general, special, incidental, or
353	consequential damages arising out of the use or inability to use the
354	software (including but not limited to loss of data or data being
355	rendered inaccurate or losses sustained by you or third parties or a
356	failure of the software to operate with any other software), even if
357	such holder or other party has been advised of the possibility of such
358	damages.
359
360	SEE ALSO
361	OpenID
362	Net::OpenID::Server, Net::OpenID::VerifiedIdentity,
363	Net::OpenID::Consumer, <http://openid.net/>,
364	<http://openid.net/developers/specs/>, and
365	<http://openid.net/extensions/sreg/1.1>.
366
367	Catalyst Authentication
368	Catalyst, Catalyst::Plugin::Authentication,
369	Catalyst::Manual::Tutorial::Authorization, and
370	Catalyst::Manual::Tutorial::Authentication.
371
372	Catalyst Configuration
373	Catalyst::Plugin::ConfigLoader, Config::General, and YAML.
374
375	Miscellaneous
376	Catalyst::Manual::Tutorial, Template, LWPx::ParanoidAgent.
788804c2	377