| Current Path : /proc/2/root/usr/OAuth-Lite-1.32/blib/man3/ |
| Current File : //proc/2/root/usr/OAuth-Lite-1.32/blib/man3/OAuth::Lite::Consumer.3pm |
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "OAuth::Lite::Consumer 3"
.TH OAuth::Lite::Consumer 3 "2014-01-04" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
OAuth::Lite::Consumer \- consumer agent
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 8
\& my $consumer = OAuth::Lite::Consumer\->new(
\& consumer_key => $consumer_key,
\& consumer_secret => $consumer_secret,
\& site => q{http://api.example.org},
\& request_token_path => q{/request_token},
\& access_token_path => q{/access_token},
\& authorize_path => q{http://example.org/authorize},
\& );
\&
\& # At first you have to publish request\-token, and
\& # with it, redirect end\-user to authorization\-url that Service Provider tell you beforehand.
\&
\& my $request_token = $consumer\->get_request_token(
\& callback_url => q{http://yourservice/callback},
\& );
\&
\& $your_app\->session\->set( request_token => $request_token );
\&
\& $your_app\->redirect( $consumer\->url_to_authorize(
\& token => $request_token,
\& ) );
\&
\& # After user authorize the request on a Service Provider side web application.
\&
\& my $verifier = $your_app\->request\->param(\*(Aqoauth_verifier\*(Aq);
\& my $request_token = $your_app\->session\->get(\*(Aqrequest_token\*(Aq);
\&
\& my $access_token = $consumer\->get_access_token(
\& token => $request_token,
\& verifier => $verifier,
\& );
\&
\& $your_app\->session\->set( access_token => $access_token );
\& $your_app\->session\->remove(\*(Aqrequest_token\*(Aq);
\&
\& # After all, you can request protected\-resources with access token
\&
\& my $access_token = $your_app\->session\->get(\*(Aqaccess_token\*(Aq);
\&
\& my $res = $consumer\->request(
\& method => \*(AqGET\*(Aq,
\& url => q{http://api.example.org/picture},
\& token => $access_token,
\& params => { file => \*(Aqmypic.jpg\*(Aq, size => \*(Aqsmall\*(Aq },
\& );
\&
\& unless ($res\->is_success) {
\& if ($res\->status == 400 || $res\->status == 401) {
\& my $auth_header = $res\->header(\*(AqWWW\-Authenticate\*(Aq);
\& if ($auth_header && $auth_header =~ /^OAuth/) {
\& # access token may be expired,
\& # get request\-token and authorize again
\& } else {
\& # another auth error.
\& }
\& }
\& # another error.
\& }
\&
\& # OAuth::Lite::Agent automatically adds Accept\-Encoding gzip header to
\& # request, so, when you use default agent, call decoded_content.
\& my $resource = $res\->decoded_content || $res\->content;
\&
\& $your_app\->handle_resource($resource);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module helps you to build OAuth Consumer application.
.SH "PAY ATTENTION"
.IX Header "PAY ATTENTION"
If you use OAuth 1.31 or older version, its has invalid way to normalize params.
(when there are two or more same key and they contain \s-1ASCII\s0 and non \s-1ASCII\s0 value)
.PP
But the many services have already supported deprecated version,
and the correct way breaks backward compatibility.
So, from 1.32, supported both correct and deprecated method.
.PP
use \f(CW$OAuth::Lite::USE_DEPRECATED_NORMALIZER\fR to switch behaviour.
Currently 1 is set by default to keep backward compatibility.
.PP
.Vb 2
\& use OAuth::Lite::Consumer;
\& use OAuth::Lite;
\&
\& $OAuth::Lite::USE_DEPRECATED_NORMALIZER = 0;
\& ...
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new(%args)"
.IX Subsection "new(%args)"
\fIparameters\fR
.IX Subsection "parameters"
.IP "consumer_key" 4
.IX Item "consumer_key"
consumer_key value
.IP "consumer_secret" 4
.IX Item "consumer_secret"
consumer_secret value
.IP "signature_method" 4
.IX Item "signature_method"
Signature method you can choose from '\s-1HMAC\-SHA1\s0', '\s-1PLAINTEXT\s0', and '\s-1RSA\-SHA1\s0' (optional, '\s-1HMAC\-SHA1\s0' is set by default)
.IP "http_method" 4
.IX Item "http_method"
\&\s-1HTTP\s0 method (\s-1GET\s0 or \s-1POST\s0) when the request is for request token or access token. (optional, '\s-1POST\s0' is set by default)
.IP "auth_method" 4
.IX Item "auth_method"
OAuth::Lite::AuthMethod's value you can choose from \s-1AUTH_HEADER\s0, \s-1POST_BODY\s0 and \s-1URL_QUERY\s0 (optional, \s-1AUTH_HEADER\s0 is set by default)
.IP "realm" 4
.IX Item "realm"
The OAuth realm value for a protected-resource you wanto to access to. (optional. empty-string is set by default)
.IP "use_request_body_hash" 4
.IX Item "use_request_body_hash"
If you use Request Body Hash extension, set 1.
See Also <http://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/drafts/4/spec.html>
.IP "site" 4
.IX Item "site"
The base site url of Service Provider
.IP "request_token_path" 4
.IX Item "request_token_path"
.PD 0
.IP "access_token_path" 4
.IX Item "access_token_path"
.IP "authorize_path" 4
.IX Item "authorize_path"
.IP "callback_url" 4
.IX Item "callback_url"
.PD
.PP
Site and other paths, simple usage.
.PP
.Vb 7
\& my $consumer = OAuth::Lite::Consumer\->new(
\& ...
\& site => q{http://example.org},
\& request_token_path => q{/request_token},
\& access_token_path => q{/access_token},
\& authorize_path => q{/authorize},
\& );
\&
\& say $consumer\->request_token_url; # http://example.org/request_token
\& say $consumer\->access_token_url; # http://example.org/access_token
\& say $consumer\->authorization_url; # http://example.org/authorize
.Ve
.PP
If the authorization_url is run under another domain, for example.
.PP
.Vb 10
\& my $consumer = OAuth::Lite::Consumer\->new(
\& ...
\& site => q{http://api.example.org},
\& request_token_path => q{/request_token},
\& access_token_path => q{/access_token},
\& authorize_path => q{http://www.example.org/authorize},
\& );
\& say $consumer\->request_token_url; # http://api.example.org/request_token
\& say $consumer\->access_token_url; # http://api.example.org/access_token
\& say $consumer\->authorization_url; # http://www.example.org/authorize
.Ve
.PP
Like this, if you pass absolute url, consumer uses them as it is.
.PP
You can omit site param, if you pass all paths as absolute url.
.PP
.Vb 6
\& my $consumer = OAuth::Lite::Consumer\->new(
\& ...
\& request_token_path => q{http://api.example.org/request_token},
\& access_token_path => q{http://api.example.org/access_token},
\& authorize_path => q{http://www.example.org/authorize},
\& );
.Ve
.PP
And there is a flexible way.
.PP
.Vb 5
\& # don\*(Aqt set each paths here.
\& my $consumer = OAuth::Lite::Consumer\->new(
\& consumer_key => $consumer_key,
\& consumer_secret => $consumer_secret,
\& );
\&
\& # set request token url here directly
\& my $rtoken = $consumer\->get_request_token(
\& url => q{http://api.example.org/request_token},
\& callback_url => q{http://www.yourservice/callback},
\& );
\&
\& # set authorize path here directly
\& my $url = $consumer\->url_to_authorize(
\& token => $rtoken,
\& url => q{http://www.example.org/authorize},
\& );
\&
\& # set access token url here directly
\& my $atoken = $consumer\->get_access_token(
\& url => q{http://api.example.org/access_token},
\& verifier => $verfication_code,
\& );
.Ve
.PP
So does callback_url. You can set it on consutructor or get_request_token method directly.
.PP
.Vb 6
\& my $consumer = OAuth::Lite::Consumer\->new(
\& ...
\& callback_url => q{http://www.yourservice/callback},
\& );
\& ...
\& my $url = $consumer\->get_request_token();
.Ve
.PP
Or
.PP
.Vb 7
\& my $consumer = OAuth::Lite::Consumer\->new(
\& ...
\& );
\& ...
\& my $url = $consumer\->get_request_token(
\& callback_url => q{http://www.yourservice/callback},
\& );
.Ve
.SS "request_token_url"
.IX Subsection "request_token_url"
.SS "access_token_url"
.IX Subsection "access_token_url"
.SS "authorization_url"
.IX Subsection "authorization_url"
.SS "url_to_authorize(%params)"
.IX Subsection "url_to_authorize(%params)"
\fIparameters\fR
.IX Subsection "parameters"
.IP "url" 4
.IX Item "url"
authorization url, you can omit this if you set authorization_path on constructor.
.IP "token" 4
.IX Item "token"
request token value
.PP
.Vb 5
\& my $url = $consumer\->url_to_authorize(
\& url => q{http://example.org/authorize},
\& token => $request_token,
\& callback_url => q{http://www.yousrservice/callback},
\& );
.Ve
.SS "obtain_request_token(%params)"
.IX Subsection "obtain_request_token(%params)"
Returns a request token as an OAuth::Lite::Response object.
Except for that, this method behaves same as get_request_token.
.SS "get_request_token(%params)"
.IX Subsection "get_request_token(%params)"
Returns a request token as an OAuth::Lite::Token object.
.PP
\fIparameters\fR
.IX Subsection "parameters"
.IP "url" 4
.IX Item "url"
Request token url. You can omit this if you set request_token_path on constructor
.IP "realm" 4
.IX Item "realm"
Realm for the resource you want to access to.
You can omit this if you set realm on constructor.
.IP "callback_url" 4
.IX Item "callback_url"
Url which service provider redirect end-user to after authorization.
You can omit this if you set callback_url on constructor.
.PP
.Vb 4
\& my $token = $consumer\->get_request_token(
\& url => q{http://api.example.org/request_token},
\& realm => q{http://api.example.org/picture},
\& ) or die $consumer\->errstr;
\&
\& say $token\->token;
\& say $token\->secret;
.Ve
.SS "obtain_access_token"
.IX Subsection "obtain_access_token"
.Vb 8
\& my $res = $consumer\->obtain_access_token(
\& url => $access_token_url,
\& params => {
\& x_auth_username => "myname",
\& x_auth_password => "mypass",
\& x_auth_mode => "client_auth",
\& },
\& );
\&
\& my $access_token = $res\->token;
\& say $acces_token\->token;
\& say $acces_token\->secret;
\& my $expires = $res\->param(\*(Aqx_auth_expires\*(Aq);
.Ve
.PP
What is the difference between obtain_access_token and get_access_token?
get_access_token requires token and verifier.
obtain_access_token doesn't. these parameters are optional.
You can pass extra parameters like above example.(see x_auth_XXX parameters)
And get_access_token returns OAuth::Lite::Token object directly,
obtain_access_token returns OAuth::Lite::Response object that includes
not only Token object but also other response parameters.
the extra parameters are used for some extensions.(Session extension, xAuth, etc.)
.PP
Of cource, if you don't need to handle these extensions,
You can continue to use get_access_token for backward compatibility.
.PP
.Vb 5
\& my $token = $consumer\->get_access_token(
\& url => $access_token_url,
\& token => $request_token,
\& verifier => $verification_code,
\& );
\&
\& # above code\*(Aqs behavior is same as (but response objects are different)
\&
\& my $res = $consumer\->obtain_access_token(
\& url => $access_token_url,
\& token => $request_token,
\& params => {
\& oauth_verifier => $verification_code,
\& },
\& );
.Ve
.SS "get_access_token(%params)"
.IX Subsection "get_access_token(%params)"
Returns a access token as an OAuth::Lite::Token object.
.PP
\fIparameters\fR
.IX Subsection "parameters"
.IP "url" 4
.IX Item "url"
Request token url. You can omit this if you set request_token_path on constructor
.IP "realm" 4
.IX Item "realm"
Realm for the resource you want to access to.
You can omit this if you set realm on constructor.
.IP "token" 4
.IX Item "token"
Request token object.
.IP "verifier" 4
.IX Item "verifier"
Verfication code which provider returns.
.PP
.Vb 6
\& my $token = $consumer\->get_access_token(
\& url => q{http://api.example.org/request_token},
\& realm => q{http://api.example.org/picture},
\& token => $request_token,
\& verifier => $verification_code,
\& ) or die $consumer\->errstr;
\&
\& say $token\->token;
\& say $token\->secret;
.Ve
.SS "gen_oauth_request(%args)"
.IX Subsection "gen_oauth_request(%args)"
Returns HTTP::Request object.
.PP
.Vb 9
\& my $req = $consumer\->gen_oauth_request(
\& method => \*(AqGET\*(Aq,
\& url => \*(Aqhttp://example.com/\*(Aq,
\& headers => [ Accept => q{...}, \*(AqContent\-Type\*(Aq => q{...}, ... ],
\& content => $content,
\& realm => $realm,
\& token => $token,
\& params => { file => \*(Aqmypic.jpg\*(Aq, size => \*(Aqsmall\*(Aq },
\& );
.Ve
.SS "request(%params)"
.IX Subsection "request(%params)"
Returns HTTP::Response object.
.PP
\fIparameters\fR
.IX Subsection "parameters"
.IP "realm" 4
.IX Item "realm"
Realm for a resource you want to access
.IP "token" 4
.IX Item "token"
Access token OAuth::Lite::Token object
.IP "method" 4
.IX Item "method"
\&\s-1HTTP\s0 method.
.IP "url" 4
.IX Item "url"
Request \s-1URL\s0
.IP "parmas" 4
.IX Item "parmas"
Extra params.
.IP "content" 4
.IX Item "content"
body data sent when method is \s-1POST\s0 or \s-1PUT\s0.
.PP
.Vb 9
\& my $response = $consumer\->request(
\& method => \*(AqPOST\*(Aq,
\& url => \*(Aqhttp://api.example.com/picture\*(Aq,
\& headers => [ Accept => q{...}, \*(AqContent\-Type\*(Aq => q{...}, ... ],
\& content => $content,
\& realm => $realm,
\& token => $access_token,
\& params => { file => \*(Aqmypic.jpg\*(Aq, size => \*(Aqsmall\*(Aq },
\& );
\&
\& unless ($response\->is_success) {
\& ...
\& }
.Ve
.SS "get"
.IX Subsection "get"
There are simple methods to request protected resources.
You need to obtain access token and set it to consumer beforehand.
.PP
.Vb 7
\& my $access_token = $consumer\->get_access_token(
\& token => $request_token,
\& verifier => $verifier,
\& );
\& # when successfully got an access\-token,
\& # it internally execute saving method like following line.
\& # $consumer\->access_token( $access_token )
.Ve
.PP
or
my \f(CW$access_token\fR = \f(CW$your_app\fR\->\fIpick_up_saved_access_token()\fR;
\f(CW$consumer\fR\->access_token($access_token);
.PP
Then you can access protected resource in a simple way.
.PP
.Vb 4
\& my $res = $consumer\->get( \*(Aqhttp://api.example.com/pictures\*(Aq );
\& if ($res\->is_success) {
\& say $res\->decoded_content||$res\->content;
\& }
.Ve
.PP
This is same as
.PP
.Vb 7
\& my $res = $consumer\->request(
\& method => q{GET},
\& url => q{http://api.example.com/picture},
\& );
\& if ($res\->is_success) {
\& say $res\->decoded_content||$res\->content;
\& }
.Ve
.SS "post"
.IX Subsection "post"
.Vb 4
\& $res = $consumer\->post( \*(Aqhttp://api.example.com/pictures\*(Aq, $content );
\& if ($res\->is_success) {
\& ...
\& }
.Ve
.PP
This is same as
.PP
.Vb 8
\& $res = $consumer\->request(
\& method => q{POST},
\& url => q{http://api.example.com/picture},
\& content => $content,
\& );
\& if ($res\->is_success) {
\& ...
\& }
.Ve
.SS "put"
.IX Subsection "put"
.Vb 4
\& $res = $consumer\->put( \*(Aqhttp://api.example.com/pictures\*(Aq, $content );
\& if ($res\->is_success) {
\& ...
\& }
.Ve
.PP
This is same as
.PP
.Vb 8
\& my $res = $consumer\->request(
\& method => q{PUT},
\& url => q{http://api.example.com/picture},
\& content => $content,
\& );
\& if ($res\->is_success) {
\& ...
\& }
.Ve
.SS "delete"
.IX Subsection "delete"
.Vb 4
\& my $res = $consumer\->delete(\*(Aqhttp://api.example.com/delete\*(Aq);
\& if ($res\->is_success) {
\& ...
\& }
.Ve
.PP
This is same as
.PP
.Vb 7
\& my $res = $consumer\->request(
\& method => q{DELETE},
\& url => q{http://api.example.com/picture},
\& );
\& if ($res\->is_success) {
\& ...
\& }
.Ve
.SS "find_realm_from_last_response"
.IX Subsection "find_realm_from_last_response"
.ie n .SS "gen_auth_header($http_method, $request_url, $params);"
.el .SS "gen_auth_header($http_method, \f(CW$request_url\fP, \f(CW$params\fP);"
.IX Subsection "gen_auth_header($http_method, $request_url, $params);"
\fIparameters\fR
.IX Subsection "parameters"
.IP "realm" 4
.IX Item "realm"
realm for a resource you want to access
.IP "token" 4
.IX Item "token"
OAuth::Lite::Token object(optional)
.PP
.Vb 4
\& my $header = $consumer\->gen_auth_header($method, $url, {
\& realm => $realm,
\& token => $token,
\& });
.Ve
.ie n .SS "gen_auth_query($http_method, $ruqest_url, $token, $extra)"
.el .SS "gen_auth_query($http_method, \f(CW$ruqest_url\fP, \f(CW$token\fP, \f(CW$extra\fP)"
.IX Subsection "gen_auth_query($http_method, $ruqest_url, $token, $extra)"
.ie n .SS "gen_auth_params($http_method, $request_url, [$token])"
.el .SS "gen_auth_params($http_method, \f(CW$request_url\fP, [$token])"
.IX Subsection "gen_auth_params($http_method, $request_url, [$token])"
Generates and returns all oauth params.
.PP
.Vb 7
\& my $params = $consumer\->gen_auth_params($http_method, $request_url);
\& say $params\->{oauth_consumer_key};
\& say $params\->{oauth_timestamp};
\& say $params\->{oauth_nonce};
\& say $params\->{oauth_signature_method};
\& say $params\->{oauth_signature};
\& say $params\->{oauth_version};
.Ve
.PP
If you pass token as third argument, the result includes oauth_token value.
.PP
.Vb 8
\& my $params = $consumer\->gen_auth_params($http_method, $request_url, $token);
\& say $params\->{oauth_consumer_key};
\& say $params\->{oauth_timestamp};
\& say $params\->{oauth_nonce};
\& say $params\->{oauth_signature_method};
\& say $params\->{oauth_signature};
\& say $params\->{oauth_token};
\& say $params\->{oauth_version};
.Ve
.SS "oauth_request"
.IX Subsection "oauth_request"
.SS "oauth_req"
.IX Subsection "oauth_req"
Returns last oauth request.
.PP
.Vb 2
\& my $req_token = $consumer\->get_request_token(...);
\& say $consumer\->oauth_request\->uri;
\&
\& my $req_token = $consumer\->get_access_token(...);
\& say $consumer\->oauth_request\->uri;
.Ve
.SS "oauth_response"
.IX Subsection "oauth_response"
.SS "oauth_res"
.IX Subsection "oauth_res"
Returns last oauth response.
.PP
.Vb 2
\& my $req_token = $consumer\->get_request_token(...);
\& say $consumer\->oauth_response\->status;
\&
\& my $req_token = $consumer\->get_access_token(...);
\& say $consumer\->oauth_response\->status;
.Ve
.SS "oauth_clear"
.IX Subsection "oauth_clear"
remove last oauth-request and oauth-response.
.SS "build_body_hash"
.IX Subsection "build_body_hash"
Build body hash according to the spec for 'OAuth Request Body Hash extension'
http://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/drafts/4/spec.html
.PP
.Vb 1
\& my $hash = $self\->build_body_hash($content);
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Lyo Kato, \f(CW\*(C`lyo.kato _at_ gmail.com\*(C'\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.
Copyright 2K16 - 2K18 Indonesian Hacker Rulez
;?>)