Net::Twitter::Role::OAuth(3pm)

1Net::Twitter::Role::OAuUtshe(r3)Contributed Perl DocumenNteatt:i:oTnwitter::Role::OAuth(3)
2
3
4

NAME

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

VERSION

10       version 4.01043
11

SYNOPSIS

13         use Net::Twitter;
14
15         my $nt = Net::Twitter->new(
16             traits          => ['API::RESTv1_1', 'OAuth'],
17             consumer_key    => "YOUR-CONSUMER-KEY",
18             consumer_secret => "YOUR-CONSUMER-SECRET",
19         );
20
21         # Do some Authentication work. See EXAMPLES
22
23         my $tweets = $nt->friends_timeline;
24         my $res    = $nt->update({ status => "I CAN HAZ OAUTH!" });
25

DESCRIPTION

27       Net::Twitter::Role::OAuth is a Net::Twitter role that provides OAuth
28       authentication instead of the default Basic Authentication.
29
30       Note that this client only works with APIs that are compatible to OAuth
31       authentication.
32

IMPORTANT

34       Beginning with version 3.02, it is necessary for web applications to
35       pass the "callback" parameter to "get_authorization_url".  In the
36       absence of a callback parameter, when the user authorizes the
37       application a PIN number is displayed rather than redirecting the user
38       back to your site.
39

EXAMPLES

41       See the "examples" directory in this distribution for working examples
42       of both desktop and web applications.
43
44       Here's how to authorize users as a desktop app mode:
45
46         use Net::Twitter;
47
48         my $nt = Net::Twitter->new(
49             traits          => ['API::RESTv1_1', 'OAuth'],
50             consumer_key    => "YOUR-CONSUMER-KEY",
51             consumer_secret => "YOUR-CONSUMER-SECRET",
52         );
53
54         # You'll save the token and secret in cookie, config file or session database
55         my($access_token, $access_token_secret) = restore_tokens();
56         if ($access_token && $access_token_secret) {
57             $nt->access_token($access_token);
58             $nt->access_token_secret($access_token_secret);
59         }
60
61         unless ( $nt->authorized ) {
62             # The client is not yet authorized: Do it now
63             print "Authorize this app at ", $nt->get_authorization_url, " and enter the PIN#\n";
64
65             my $pin = <STDIN>; # wait for input
66             chomp $pin;
67
68             my($access_token, $access_token_secret, $user_id, $screen_name) = $nt->request_access_token(verifier => $pin);
69             save_tokens($access_token, $access_token_secret); # if necessary
70         }
71
72         # Everything's ready
73
74       In a web application mode, you need to save the oauth_token and
75       oauth_token_secret somewhere when you redirect the user to the OAuth
76       authorization URL.
77
78         sub twitter_authorize : Local {
79             my($self, $c) = @_;
80
81             my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
82             my $url = $nt->get_authorization_url(callback => $callbackurl);
83
84             $c->response->cookies->{oauth} = {
85                 value => {
86                     token => $nt->request_token,
87                     token_secret => $nt->request_token_secret,
88                 },
89             };
90
91             $c->response->redirect($url);
92         }
93
94       And when the user returns back, you'll reset those request token and
95       secret to upgrade the request token to access token.
96
97         sub twitter_auth_callback : Local {
98             my($self, $c) = @_;
99
100             my %cookie = $c->request->cookies->{oauth}->value;
101             my $verifier = $c->req->params->{oauth_verifier};
102
103             my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
104             $nt->request_token($cookie{token});
105             $nt->request_token_secret($cookie{token_secret});
106
107             my($access_token, $access_token_secret, $user_id, $screen_name)
108                 = $nt->request_access_token(verifier => $verifier);
109
110             # Save $access_token and $access_token_secret in the database associated with $c->user
111         }
112
113       Later on, you can retrieve and reset those access token and secret
114       before calling any Twitter API methods.
115
116         sub make_tweet : Local {
117             my($self, $c) = @_;
118
119             my($access_token, $access_token_secret) = ...;
120
121             my $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 OAuth/], %param);
122             $nt->access_token($access_token);
123             $nt->access_token_secret($access_token_secret);
124
125             # Now you can call any Net::Twitter API methods on $nt
126             my $status = $c->req->param('status');
127             my $res = $nt->update({ status => $status });
128         }
129

METHODS

131       authorized
132           Whether the client has the necessary credentials to be authorized.
133
134           Note that the credentials may be wrong and so the request may fail.
135
136       request_access_token(verifier => $verifier)
137           Request the access token, access token secret, user id and screen
138           name for this user. You must pass the PIN# (for desktop
139           applications) or the "oauth_verifier" value, provided as a
140           parameter to the oauth callback (for web applications) as
141           $verifier.
142
143           The user must have authorized this app at the url given by
144           "get_authorization_url" first.
145
146           Returns the access_token, access_token_secret, user_id, and
147           screen_name in a list.  Also sets them internally so that after
148           calling this method, you can immediately call API methods requiring
149           authentication.
150
151       xauth($username, $password)
152           Exchanges the $username and $password for access tokens.  This
153           method has the same return value as "request_access_token":
154           access_token, access_token_secret, user_id, and screen_name in a
155           list. Also, like "request_access_token", it sets the access_token
156           and access_secret, internally, so you can immediately call API
157           methods requiring authentication.
158
159       get_authorization_url(callback => $callback_url)
160           Get the URL used to authorize the user.  Returns a "URI" object.
161           For web applications, pass your applications callback URL as the
162           "callback" parameter.  No arguments are required for desktop
163           applications ("callback" defaults to "oob", out-of-band).
164
165       get_authentication_url(callback => $callback_url)
166           Get the URL used to authenticate the user with "Sign in with
167           Twitter" authentication flow.  Returns a "URI" object.  For web
168           applications, pass your applications callback URL as the "callback"
169           parameter.  No arguments are required for desktop applications
170           ("callback" defaults to "oob", out-of-band).
171
172       access_token
173           Get or set the access token.
174
175       access_token_secret
176           Get or set the access token secret.
177
178       request_token
179           Get or set the request token.
180
181       request_token_secret
182           Get or set the request token secret.
183

DEPRECATED METHODS

185       oauth
186           Prior versions used Net::OAuth::Simple.  This method provided
187           access to the contained Net::OAuth::Simple object. Beginning with
188           Net::Twitter 3.00, the OAuth methods were delegated to
189           Net::OAuth::Simple.  They have since made first class methods.
190           Net::Simple::OAuth is no longer used.  A warning will be displayed
191           when accessing OAuth methods via the <oauth> method.  The "oauth"
192           method will be removed in a future release.
193
194       is_authorized
195           Use "authorized" instead.
196
197       oauth_authorization_url
198           Use "get_authorization_url" instead.
199
200       oauth_token
201              $nt->oauth_token($access_token, $access_token_secret);
202
203           Use "access_token" and "access_token_seccret" instead:
204
205              $nt->access_token($access_token);
206              $nt->access_token_secret($access_token_secret);
207

ACKNOWLEDGEMENTS

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

AUTHORS

216       Marc Mims <marc@questright.com>
217
218       Tatsuhiko Miyagawa <miyagawa@bulknews.net>
219

LICENSE

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