File Coverage

blib/lib/Net/Twitter/Role/OAuth.pm

Criterion	Covered	Total	%
statement	31	83	37.3
branch	1	8	12.5
condition	2	5	40.0
subroutine	10	25	40.0
pod	9	9	100.0
total	53	130	40.7

package Net::Twitter::Role::OAuth;
$Net::Twitter::Role::OAuth::VERSION = '4.01010';
use Moose::Role;
use HTTP::Request::Common;
use Carp::Clan qw/^(?:Net::Twitter|Moose|Class::MOP)/;
use URI;
use Digest::SHA;
use List::Util qw/first/;

requires qw/_add_authorization_header ua/;

use namespace::autoclean;

use Net::OAuth;
$Net::OAuth::PROTOCOL_VERSION = Net::OAuth::PROTOCOL_VERSION_1_0A;

# flatten oauth_urls with defaults
around BUILDARGS => sub {
    my $orig  = shift;
    my $class = shift;

    my $args = $class->$orig(@_);
    my $oauth_urls = delete $args->{oauth_urls} || {
        request_token_url  => "https://api.twitter.com/oauth/request_token",
        authentication_url => "https://api.twitter.com/oauth/authenticate",
        authorization_url  => "https://api.twitter.com/oauth/authorize",
        access_token_url   => "https://api.twitter.com/oauth/access_token",
        xauth_url          => "https://api.twitter.com/oauth/access_token",
    };

    return { %$oauth_urls, %$args };
};

has consumer_key    => ( isa => 'Str', is => 'ro', required => 1 );
has consumer_secret => ( isa => 'Str', is => 'ro', required => 1 );

# url attributes
for my $attribute ( qw/authentication_url authorization_url request_token_url access_token_url xauth_url/ ) {
    has $attribute => (
        isa    => 'Str', is => 'rw', required => 1,
        # inflate urls to URI objects when read
        reader => { $attribute => sub { URI->new(shift->{$attribute}) } },
    );
}

# token attributes
for my $attribute ( qw/access_token access_token_secret request_token request_token_secret/ ) {
    has $attribute => ( isa => 'Str', is => 'rw',
                        clearer   => "clear_$attribute",
                        predicate => "has_$attribute",
    );
}

# simple check to see if we have access tokens; does not check to see if they are valid
sub authorized {
    my $self = shift;

    return defined $self->has_access_token && $self->has_access_token_secret;
}

# get the authorization or authentication url
sub _get_auth_url {
    my ($self, $which_url, %params ) = @_;

    my $callback = delete $params{callback} || 'oob';
    $self->_request_request_token(callback => $callback);

    my $uri = $self->$which_url;
    $uri->query_form(oauth_token => $self->request_token, %params);
    return $uri;
}

# get the authentication URL from Twitter
sub get_authentication_url { return shift->_get_auth_url(authentication_url => @_) }

# get the authorization URL from Twitter
sub get_authorization_url { return shift->_get_auth_url(authorization_url => @_) }

# common portion of all oauth requests
sub _make_oauth_request {
    my ($self, $type, %params) = @_;

    my $class = $type =~ s/^\+// ? $type : Net::OAuth->request($type);
    my $request = $class->new(
        version          => '1.0',
        consumer_key     => $self->{consumer_key},
        consumer_secret  => $self->{consumer_secret},
        request_method   => 'GET',
        signature_method => 'HMAC-SHA1',
        timestamp        => time,
        nonce            => Digest::SHA::sha1_base64(time . $$ . rand),
        %params,
    );

    $request->sign;

    return $request;
}

# called by get_authorization_url to obtain request tokens
sub _request_request_token {
    my ($self, %params) = @_;

    my $uri = $self->request_token_url;
    my $request = $self->_make_oauth_request(
        'request token',
        request_url => $uri,
        %params,
    );

    my $msg = HTTP::Request->new(GET => $uri);
    $msg->header(authorization => $request->to_authorization_header);

    my $res = $self->_send_request($msg);
    croak "GET $uri failed: ".$res->status_line
        unless $res->is_success;

    # reuse $uri to extract parameters from the response content
    $uri->query($res->content);
    my %res_param = $uri->query_form;

    $self->request_token($res_param{oauth_token});
    $self->request_token_secret($res_param{oauth_token_secret});
}

# exchange request tokens for access tokens; call with (verifier => $verifier)
sub request_access_token {
    my ($self, %params ) = @_;

    my $uri = $self->access_token_url;
    my $request = $self->_make_oauth_request(
        'access token',
        request_url => $uri,
        token       => $self->request_token,
        token_secret => $self->request_token_secret,
        %params, # verifier => $verifier
    );

    my $msg = HTTP::Request->new(GET => $uri);
    $msg->header(authorization => $request->to_authorization_header);

    my $res = $self->_send_request($msg);
    croak "GET $uri failed: ".$res->status_line
        unless $res->is_success;

    # discard request tokens, they're no longer valid
    $self->clear_request_token;
    $self->clear_request_token_secret;

    # reuse $uri to extract parameters from content
    $uri->query($res->content);
    my %res_param = $uri->query_form;

    return (
        $self->access_token($res_param{oauth_token}),
        $self->access_token_secret($res_param{oauth_token_secret}),
        $res_param{user_id},
        $res_param{screen_name},
    );
}

around _prepare_request => sub {
    my $orig = shift;
    my ($self, $http_method, $uri, $args, $authenticate) = @_;

    delete $args->{source};
    $orig->(@_);
};

override _add_authorization_header => sub {
    my ( $self, $msg, $args ) = @_;

    return unless $self->authorized;

    my $is_multipart = grep { ref } %$args;

    local $Net::OAuth::SKIP_UTF8_DOUBLE_ENCODE_CHECK = 1;

    my $uri = $msg->uri->clone;
    $uri->query(undef);

    my $request = $self->_make_oauth_request(
        'protected resource',
        request_url    => $uri,
        request_method => $msg->method,
        token          => $self->access_token,
        token_secret   => $self->access_token_secret,
        extra_params   => $is_multipart ? {} : $args,
    );

    $msg->header(authorization => $request->to_authorization_header);
};

sub xauth {
    my ( $self, $username, $password ) = @_;

    my @args = (
        x_auth_username => $username,
        x_auth_password => $password,
        x_auth_mode     => 'client_auth',
    );

    my $uri = $self->xauth_url;
    my $request = $self->_make_oauth_request(
        'XauthAccessToken',
        request_url    => $uri,
        request_method => 'POST',
        @args,
    );

    my $res = $self->ua->request(
        POST $uri, \@args, Authorization => $request->to_authorization_header);
    die "POST $uri failed: ".$res->status_line
        unless $res->is_success;

    # reuse $uri to extract parameters from content
    $uri->query($res->content);
    my %res_param = $uri->query_form;

    return (
        $self->access_token($res_param{oauth_token}),
        $self->access_token_secret($res_param{oauth_token_secret}),
        $res_param{user_id},
        $res_param{screen_name},
    );
}

# shortcuts defined in early releases
# DEPRECATED

sub oauth_token {
    my($self, @tokens) = @_;

    carp "DEPRECATED: use access_token and access_token_secret instead";
    $self->access_token($tokens[0]);
    $self->access_token_secret($tokens[1]);
    return @tokens;
}

sub is_authorized {
    carp "DEPRECATED: use authorized instead";
    shift->authorized(@_)
}

sub oauth_authorization_url {
    carp "DEPRECATED: use get_authorization_url instead";
    shift->get_authorization_url(@_)
}

sub oauth {
    carp "DEPRECATED: call this method on Net::Twitter itself, rather than through the oauth accessor";
    shift
}

1;

__END__

=encoding utf-8

=for stopwords

=head1 NAME

Net::Twitter::Role::OAuth - Net::Twitter role that provides OAuth instead of Basic Authentication

=head1 VERSION

version 4.01010

=head1 SYNOPSIS

  use Net::Twitter;

  my $nt = Net::Twitter->new(
      traits          => ['API::RESTv1_1', 'OAuth'],
      consumer_key    => "YOUR-CONSUMER-KEY",
      consumer_secret => "YOUR-CONSUMER-SECRET",
  );

  # Do some Authentication work. See EXAMPLES

  my $tweets = $nt->friends_timeline;
  my $res    = $nt->update({ status => "I CAN HAZ OAUTH!" });

=head1 DESCRIPTION

Net::Twitter::Role::OAuth is a Net::Twitter role that provides OAuth
authentication instead of the default Basic Authentication.

Note that this client only works with APIs that are compatible to OAuth authentication.

=head1 IMPORTANT

Beginning with version 3.02, it is necessary for web applications to pass the
C<callback> parameter to C<get_authorization_url>.  In the absence of a
callback parameter, when the user authorizes the application a PIN number is
displayed rather than redirecting the user back to your site.

=head1 EXAMPLES

See the C<examples> directory in this distribution for working examples of both
desktop and web applications.

Here's how to authorize users as a desktop app mode:

  use Net::Twitter;

  my $nt = Net::Twitter->new(
      traits          => ['API::RESTv1_1', 'OAuth'],
      consumer_key    => "YOUR-CONSUMER-KEY",
      consumer_secret => "YOUR-CONSUMER-SECRET",
  );

  # You'll save the token and secret in cookie, config file or session database
  my($access_token, $access_token_secret) = restore_tokens();
  if ($access_token && $access_token_secret) {
      $nt->access_token($access_token);
      $nt->access_token_secret($access_token_secret);
  }

  unless ( $nt->authorized ) {
      # The client is not yet authorized: Do it now
      print "Authorize this app at ", $nt->get_authorization_url, " and enter the PIN#\n";

      my $pin = <STDIN>; # wait for input
      chomp $pin;

      my($access_token, $access_token_secret, $user_id, $screen_name) = $nt->request_access_token(verifier => $pin);
      save_tokens($access_token, $access_token_secret); # if necessary
  }

  # Everything's ready

In a web application mode, you need to save the oauth_token and
oauth_token_secret somewhere when you redirect the user to the OAuth
authorization URL.

  sub twitter_authorize : Local {
      my($self, $c) = @_;

      my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
      my $url = $nt->get_authorization_url(callback => $callbackurl);

      $c->response->cookies->{oauth} = {
          value => {
              token => $nt->request_token,
              token_secret => $nt->request_token_secret,
          },
      };

      $c->response->redirect($url);
  }

And when the user returns back, you'll reset those request token and
secret to upgrade the request token to access token.

  sub twitter_auth_callback : Local {
      my($self, $c) = @_;

      my %cookie = $c->request->cookies->{oauth}->value;
      my $verifier = $c->req->params->{oauth_verifier};

      my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
      $nt->request_token($cookie{token});
      $nt->request_token_secret($cookie{token_secret});

      my($access_token, $access_token_secret, $user_id, $screen_name)
          = $nt->request_access_token(verifier => $verifier);

      # Save $access_token and $access_token_secret in the database associated with $c->user
  }

Later on, you can retrieve and reset those access token and secret
before calling any Twitter API methods.

  sub make_tweet : Local {
      my($self, $c) = @_;

      my($access_token, $access_token_secret) = ...;

      my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
      $nt->access_token($access_token);
      $nt->access_token_secret($access_token_secret);

      # Now you can call any Net::Twitter API methods on $nt
      my $status = $c->req->param('status');
      my $res = $nt->update({ status => $status });
  }

=head1 METHODS

=over 4

=item authorized

Whether the client has the necessary credentials to be authorized.

Note that the credentials may be wrong and so the request may fail.

=item request_access_token(verifier => $verifier)

Request the access token, access token secret, user id and screen name for
this user. You must pass the PIN# (for desktop applications) or the
C<oauth_verifier> value, provided as a parameter to the oauth callback
(for web applications) as C<$verifier>.

The user must have authorized this app at the url given by C<get_authorization_url> first.

Returns the access_token, access_token_secret, user_id, and screen_name in a
list.  Also sets them internally so that after calling this method, you can
immediately call API methods requiring authentication.

=item xauth($username, $password)

Exchanges the C<$username> and C<$password> for access tokens.  This method has
the same return value as C<request_access_token>: access_token, access_token_secret,
user_id, and screen_name in a list. Also, like C<request_access_token>, it sets
the access_token and access_secret, internally, so you can immediately call API
methods requiring authentication.

=item get_authorization_url(callback => $callback_url)

Get the URL used to authorize the user.  Returns a C<URI> object.  For web
applications, pass your applications callback URL as the C<callback> parameter.
No arguments are required for desktop applications (C<callback> defaults to
C<oob>, out-of-band).

=item get_authentication_url(callback => $callback_url)

Get the URL used to authenticate the user with "Sign in with Twitter"
authentication flow.  Returns a C<URI> object.  For web applications, pass your
applications callback URL as the C<callback> parameter.  No arguments are
required for desktop applications (C<callback> defaults to C<oob>, out-of-band).

=item access_token

Get or set the access token.

=item access_token_secret

Get or set the access token secret.

=item request_token

Get or set the request token.

=item request_token_secret

Get or set the request token secret.

=back

=head1 DEPRECATED METHODS

=over 4

=item oauth

Prior versions used Net::OAuth::Simple.  This method provided access to the
contained Net::OAuth::Simple object. Beginning with Net::Twitter 3.00, the
OAuth methods were delegated to Net::OAuth::Simple.  They have since made first
class methods.  Net::Simple::OAuth is no longer used.  A warning will be
displayed when accessing OAuth methods via the <oauth> method.  The C<oauth>
method will be removed in a future release.

=item is_authorized

Use C<authorized> instead.

=item oauth_authorization_url

Use C<get_authorization_url> instead.

=item oauth_token

   $nt->oauth_token($access_token, $access_token_secret);

Use C<access_token> and C<access_token_seccret> instead:

   $nt->access_token($access_token);
   $nt->access_token_secret($access_token_secret);

=back

=head1 ACKNOWLEDGEMENTS

This module was originally authored by Tatsuhiko Miyagawa as
C<Net::Twitter::OAuth>, a subclass of the C<Net::Twitter> 2.x. It was
refactored into a Moose Role for use in C<Net::Twitter> 3.0 and above by Marc
Mims.  Many thanks to Tatsuhiko for the original work on both code and
documentation.

=head1 AUTHORS

Marc Mims E<lt>[e-mail]<gt>

Tatsuhiko Miyagawa E<lt>[e-mail]<gt>

=head1 LICENSE

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=head1 SEE ALSO

L<Net::Twitter>, L<Net::Twitter::OAuth::Simple>, L<Net::OAuth::Simple>

=cut