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 <http://tools.ietf.org/html/rfc5849>. 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)

SEE ALSO

    Net::OAuth, Mojolicious::Plugin::OAuth2

