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.

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

