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

perl v5.28.1                                       2018-12-19                                    WWW::OAuth(3pm)