1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242
|
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,
);
# Just retrieve authorization header
my $auth_header = $oauth->authorization_header($http_request, { oauth_callback => $url });
$http_request->header(Authorization => $auth_header);
# 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 <http://tools.ietf.org/html/rfc5849> (sometimes referred to as
OAuth 1.0A). 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, RSA-SHA1, or a custom
signature method. For RSA-SHA1 or custom signature methods, a "signer"
must be provided. Defaults to HMAC-SHA1.
signer
my $signer = $oauth->signer;
$oauth = $oauth->signer(sub {
my ($base_str, $client_secret, $token_secret) = @_;
...
return $signature;
});
Coderef which implements the "signature_method". A default signer is
provided for signature methods PLAINTEXT and HMAC-SHA1; this attribute
is required for other signature methods. For signature method RSA-SHA1,
this attribute may also be an object which has a sign method like
Crypt::OpenSSL::RSA.
The signer is passed the computed signature base string, the client
secret, and (if present) the token secret, and must return the
signature string.
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 sets the Authorization header using
"authorization_header" to sign the request for OAuth 1.0. An optional
hashref of OAuth parameters will be passed through to
"authorization_header". Returns the container object.
authorization_header
my $auth_header = $oauth->authorization_header($container, \%oauth_params);
my $auth_header = $oauth->authorization_header($http_request, \%oauth_params);
my $auth_header = $oauth->authorization_header(Basic => { method => 'GET', url => $url }, \%oauth_params);
Forms an OAuth 1.0 signed Authorization header for the passed request.
As in "authenticate", the request may be specified in any form accepted
by "oauth_request" in WWW::OAuth::Util. OAuth protocol parameters
(starting with oauth_ or the special parameter realm) may be optionally
specified in a hashref and will override any generated protocol
parameters of the same name (they should not be present in the request
URL or body parameters). Returns the signed header value.
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.
This module was developed primarily to interface with the Twitter API,
which is now functionally unusable, so further development of this
module is unlikely without another use case.
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)
SEE ALSO
Net::OAuth, Mojolicious::Plugin::OAuth2
|