Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/grinnz/www-oauth

WWW::OAuth - Portable OAuth 1.0 authentication
https://github.com/grinnz/www-oauth

Last synced: 5 days ago
JSON representation

WWW::OAuth - Portable OAuth 1.0 authentication

Awesome Lists containing this project

README 

        
=pod



=head1 NAME



WWW::OAuth - Portable OAuth 1.0 authentication



=head1 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);

 

=head1 DESCRIPTION



L implements OAuth 1.0 request authentication according to

L (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

L, L, L, and can be extended to

operate on other types of requests.



Some user agents can be configured to automatically authenticate each request

with a L 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) });



=head1 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 C<$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);



=head1 ATTRIBUTES



L implements the following attributes.



=head2 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.



=head2 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.



=head2 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).



=head2 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).



=head2 signature_method



 my $method = $oauth->signature_method;

 $oauth     = $oauth->signature_method($method);



Signature method, can be C, C, C, or a custom

signature method. For C or custom signature methods, a L"signer">

must be provided. Defaults to C.



=head2 signer



 my $signer = $oauth->signer;

 $oauth     = $oauth->signer(sub {

   my ($base_str, $client_secret, $token_secret) = @_;

   ...

   return $signature;

 });



Coderef which implements the L"signature_method">. A default signer is

provided for signature methods C and C; this attribute is

required for other signature methods. For signature method C, this

attribute may also be an object which has a C method like

L.



The signer is passed the computed signature base string, the client secret, and

(if present) the token secret, and must return the signature string.



=head1 METHODS



L implements the following methods.



=head2 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 L,

then sets the Authorization header using L"authorization_header"> to sign the

request for OAuth 1.0. An optional hashref of OAuth parameters will be passed

through to L"authorization_header">. Returns the container object.



=head2 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

L"authenticate">, the request may be specified in any form accepted by

L. OAuth protocol parameters (starting with

C or the special parameter C) 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.



=head1 HTTP REQUEST CONTAINERS



Request containers provide a unified interface for L"authenticate"> to parse

and update HTTP requests. They must perform the L role

L. Custom container classes can be instantiated

directly or via L.



=head2 Basic



L contains the request attributes directly, for

user agents such as L that do not use request objects.



=head2 HTTP_Request



L wraps a L object, which

is compatible with several user agents including L,

L, and L.



=head2 Mojo



L wraps a L object,

which is used by L via L.



=head1 BUGS



Report any issues on the public bugtracker.



=head1 AUTHOR



Dan Book 



=head1 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)



=head1 SEE ALSO



L, L



=cut