--- name: "Net::Twitter::Role::OAuth" section: "3pm" platform: "linux" package: "libnet-twitter-perl" version: "4.01043-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Net::Twitter::Role::OAuth" --- # Net::Twitter::Role::OAuth(3pm) Net::Twitter role that provides OAuth instead of Basic Authentication ## NAME Net::Twitter::Role::OAuth - Net::Twitter role that provides OAuth instead of Basic Authentication ## VERSION version 4.01043 ## 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!" }); ``` ## 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. ## IMPORTANT Beginning with version 3.02, it is necessary for web applications to pass the `"callback"` parameter to `"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. ## EXAMPLES See the `"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 = ; # 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 }); } ``` ## METHODS - authorized Whether the client has the necessary credentials to be authorized. Note that the credentials may be wrong and so the request may fail. - 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 `"oauth_verifier"` value, provided as a parameter to the oauth callback (for web applications) as `$verifier`. The user must have authorized this app at the url given by `"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. - xauth($username, $password) Exchanges the `$username` and `$password` for access tokens. This method has the same return value as `"request_access_token"`: access\_token, access\_token\_secret, user\_id, and screen\_name in a list. Also, like `"request_access_token"`, it sets the access\_token and access\_secret, internally, so you can immediately call API methods requiring authentication. - get\_authorization\_url(callback =\> $callback\_url) Get the URL used to authorize the user. Returns a `"URI"` object. For web applications, pass your applications callback URL as the `"callback"` parameter. No arguments are required for desktop applications (`"callback"` defaults to `"oob"`, out-of-band). - get\_authentication\_url(callback =\> $callback\_url) Get the URL used to authenticate the user with "Sign in with Twitter" authentication flow. Returns a `"URI"` object. For web applications, pass your applications callback URL as the `"callback"` parameter. No arguments are required for desktop applications (`"callback"` defaults to `"oob"`, out-of-band). - access\_token Get or set the access token. - access\_token\_secret Get or set the access token secret. - request\_token Get or set the request token. - request\_token\_secret Get or set the request token secret. ## DEPRECATED METHODS - 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 \ method. The `"oauth"` method will be removed in a future release. - is\_authorized Use `"authorized"` instead. - oauth\_authorization\_url Use `"get_authorization_url"` instead. - oauth\_token ``` $nt->oauth_token($access_token, $access_token_secret); ``` Use `"access_token"` and `"access_token_seccret"` instead: ``` $nt->access_token($access_token); $nt->access_token_secret($access_token_secret); ``` ## ACKNOWLEDGEMENTS This module was originally authored by Tatsuhiko Miyagawa as `"Net::Twitter::OAuth"`, a subclass of the `"Net::Twitter"` 2.x. It was refactored into a Moose Role for use in `"Net::Twitter"` 3.0 and above by Marc Mims. Many thanks to Tatsuhiko for the original work on both code and documentation. ## AUTHORS Marc Mims \ Tatsuhiko Miyagawa \ ## LICENSE This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ## SEE ALSO Net::Twitter, Net::Twitter::OAuth::Simple, Net::OAuth::Simple