NAME
WWW::OAuth - Portable OAuth 1.0 authentication
SYNOPSIS
use WWW::OAuth;
my $oauth = WWW::OAuth->new(
client_id => $client_id,
client_secret => $client_secret,
token => $token,
token_secret => $token_secret,
);
# HTTP::Tiny
use HTTP::Tiny;
my $res = $oauth->authenticate(Basic => { method => 'GET', url => $url })
->request_with(HTTP::Tiny->new);
# HTTP::Request
use HTTP::Request::Common;
use LWP::UserAgent;
my $res = $oauth->authenticate(GET $url)->request_with(LWP::UserAgent->new);
# Mojo::Message::Request
use Mojo::UserAgent;
my $tx = $ua->build_tx(get => $url);
$tx = $oauth->authenticate($tx->req)->request_with(Mojo::UserAgent->new);
DESCRIPTION
WWW::OAuth implements OAuth 1.0 request authentication according to RFC 5849. It does not implement the user agent requests needed for the complete OAuth 1.0 authorization flow; it only prepares and signs requests, leaving the rest up to your application. It can authenticate requests for LWP::UserAgent, Mojo::UserAgent, HTTP::Tiny, and can be extended to operate on other types of requests.
Some user agents can be configured to automatically authenticate each request with a WWW::OAuth object.
# LWP::UserAgent
my $ua = LWP::UserAgent->new;
$ua->add_handler(request_prepare => sub { $oauth->authenticate($_[0]) });
# Mojo::UserAgent
my $ua = Mojo::UserAgent->new;
$ua->on(start => sub { $oauth->authenticate($_[1]->req) });RETRIEVING ACCESS TOKENS
The process of retrieving access tokens and token secrets for authorization on behalf of a user may differ among various APIs, but it follows this general format (error checking is left as an exercise to the reader):
use WWW::OAuth;
use WWW::OAuth::Util 'form_urldecode';
use HTTP::Tiny;
my $ua = HTTP::Tiny->new;
my $oauth = WWW::OAuth->new(
client_id => $client_id,
client_secret => $client_secret,
);
# Request token request
my $res = $oauth->authenticate({ method => 'POST', url => $request_token_url },
{ oauth_callback => $callback_url })->request_with($ua);
my %res_data = @{form_urldecode $res->{content}};
my ($request_token, $request_secret) = @res_data{'oauth_token','oauth_token_secret'};
Now, the returned request token must be used to construct a URL for the user to go to and authorize your application. The exact method differs by API. The user will usually be redirected to the $callback_url passed earlier after authorizing, with a verifier token that can be used to retrieve the access token and secret.
# Access token request
$oauth->token($request_token);
$oauth->token_secret($request_secret);
my $res = $oauth->authenticate({ method => 'POST', url => $access_token_url },
{ oauth_verifier => $verifier_token })->request_with($ua);
my %res_data = @{form_urldecode $res->{content}};
my ($access_token, $access_secret) = @res_data{'oauth_token','oauth_token_secret'};
Finally, the access token and secret can now be stored and used to authorize your application on behalf of this user.
$oauth->token($access_token);
$oauth->token_secret($access_secret);ATTRIBUTES
WWW::OAuth implements the following attributes.
client_id
my $client_id = $oauth->client_id;
$oauth = $oauth->client_id($client_id);Client ID used to identify application (sometimes called an API key or consumer key). Required for all requests.
client_secret
my $client_secret = $oauth->client_secret;
$oauth = $oauth->client_secret($client_secret);Client secret used to authenticate application (sometimes called an API secret or consumer secret). Required for all requests.
token
my $token = $oauth->token;
$oauth = $oauth->token($token);Request or access token used to identify resource owner. Leave undefined for temporary credentials requests (request token requests).
token_secret
my $token_secret = $oauth->token_secret;
$oauth = $oauth->token_secret($token_secret);Request or access token secret used to authenticate on behalf of resource owner. Leave undefined for temporary credentials requests (request token requests).
signature_method
my $method = $oauth->signature_method;
$oauth = $oauth->signature_method($method);Signature method, can be PLAINTEXT, HMAC-SHA1, a coderef that implements the RSA-SHA1 method, or an object that implements the RSA-SHA1 method with a sign method like Crypt::OpenSSL::RSA. Defaults to HMAC-SHA1.
METHODS
WWW::OAuth implements the following methods.
authenticate
$container = $oauth->authenticate($container, \%oauth_params);
my $container = $oauth->authenticate($http_request, \%oauth_params);
my $container = $oauth->authenticate(Basic => { method => 'GET', url => $url }, \%oauth_params);Wraps the HTTP request in a container with "oauth_request" in WWW::OAuth::Util, then updates the request URL, content, and headers as needed to construct and sign the request for OAuth 1.0. OAuth parameters (starting with oauth_) may be optionally specified in a hashref, and will override any generated or existing OAuth parameters of the same name. Returns the container object.
HTTP REQUEST CONTAINERS
Request containers provide a unified interface for "authenticate" to parse and update HTTP requests. They must perform the Role::Tiny role WWW::OAuth::Request. Custom container classes can be instantiated directly or via "oauth_request" in WWW::OAuth::Util.
Basic
WWW::OAuth::Request::Basic contains the request attributes directly, for user agents such as HTTP::Tiny that do not use request objects.
HTTP_Request
WWW::OAuth::Request::HTTP_Request wraps a HTTP::Request object, which is compatible with several user agents including LWP::UserAgent, HTTP::Thin, and Net::Async::HTTP.
Mojo
WWW::OAuth::Request::Mojo wraps a Mojo::Message::Request object, which is used by Mojo::UserAgent via Mojo::Transaction.
BUGS
Report any issues on the public bugtracker.
AUTHOR
Dan Book <dbook@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2015 by Dan Book.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)