view release on metacpan or  search on metacpan

lib/OAuth/Consumer.pm  view on Meta::CPAN

package OAuth::Consumer;
our $VERSION = '0.03';
use strict;
use warnings;
use feature 'switch';
use Carp;
use IO::Socket::INET;
use URI::Escape;
use HTTP::Response;
use Encode;
use HTML::Entities;
use parent 'LWP::Authen::OAuth';

=encoding utf-8

=head1 NAME

OAuth::Consumer - LWP based user agent with OAuth for consumer application

=head1 SYNOPSIS

OAuth is a protocol to allow a user to authorize an application to access on its
behalf ressources on a server without giving its password to the application. To
achieve this aim OAuth have a fairly complicated 3-steps authentication mechanism
which require to user to go to a website to authenticate itself. The authentication
response is then sent-back by the user itself through a callback mechanism.

OAuth::Consumer hide away to complexity of this process, including the set-up of
a callback webserver which can be called by the user browser when its
authentication is performed.

This library is oriented toward desktop application, it could possibly be used
in a web application but I have not tried it (and the LWP setup may not be the
most appropiate in this case).

Authenticating your application with OAuth to access some user's ressources is
a matter of requesting and authorising a I<token>. This can be done with the
following steps:

  use OAuth::Consumer;
  
  my $ua = OAuth::Consumer->new(
  		oauth_consumer_key => 'key',
  		oauth_consumer_secret => 'secret'
  		oauth_request_token_url => 'http://provider/oauth/request_token',
  		oauth_authorize_url => 'http://provider/oauth/authorize',
  		oauth_access_token_url => 'http://provider/oauth/access_token'
  	);
  
  my $verifer_url = $ua->get_request_token();
  
  print "You should authentify yourself at this URL: $verifier_url\n";
  
  my ($token, $secret) = $ua->get_access_token()
  
At this point, C<$ua> is an OAuth enabled LWP user-agent that you can use to
access OAuth protected ressources. You should save the C<$token> and C<$secret>
that you got and, in a later session, you may just do the following to gain
access to the protected ressources:

  my $ua = OAuth::Consumer->new(
  		oauth_consumer_key => 'key',
  		oauth_consumer_secret => 'secret'
  		oauth_token_=> $token,
  		oauth_token_secret => $secret
  	);

=head1 DESCRIPTION

As OAuth::Consumer is a high-level library, this documentation does not describe
precisely the OAuth protocol. You may find documentation on this protocol on
these websites:

=over 4

=item L<http://markdown.io/https://raw.github.com/Dynalon/Rainy/master/docs/OAUTH.md>

=item L<http://hueniverse.com/oauth/guide/authentication/>

=item L<http://code.google.com/p/oauthconsumer/wiki/UsingOAuthConsumer>

=item L<http://tools.ietf.org/html/rfc5849>

=back


=head1 CONSTRUCTOR

  my $ua = OAuth::Consumer->new(%args);

The OAuth::Consumer constructor gives you an LWP::UserAgent object (well, strictly
speaking this is an LWP::Authen::OAuth object, but you should not use directly