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 parameters (starting with
   oauth_) may be optionally specified in a hashref and will override any
   generated OAuth 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 <[email protected]>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.