/ 
OAuth-Lite-1.08
River stage one • 9 direct dependents • 9 total dependents
/ OAuth::Lite::Consumer

NAME

OAuth::Lite::Consumer - consumer agent

SYNOPSIS

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();

$your_app->session->set( request_token => $request_token );

$your_app->redirect( $consumer->url_to_authorize(
    token        => $request_token,
    callback_url => q{http://yourservice/callback},
) );

# After user authorize the request on a Service Provider side web application.

my $request_token = $your_app->session->get('request_token');

my $access_token = $consumer->get_access_token( token => $request_token );

$your_app->session->set( access_token => $access_token );
$your_app->session->remove('request_token');

# After all, you can request protected-resource with access token

my $access_token = $your_app->session->get('access_token');

my $res = $consumer->request(
    method => 'GET', 
    url    => q{http://api.example.org/picture},
    token  => $access_token,
    params => { file => 'mypic.jpg', size => 'small' },
);

unless ($res->is_success) {
    if ($res->status == 400 || $res->status == 401) {
        my $auth_header = $res->header('WWW-Authenticate');
        if ($auth_header && $auth_header =~ /^OAuth/) {
            # access token may be expired,
            # get request-token and authorize again
        } else {
            # another auth error.
        }
    }
    # another error.
}

my $resource = $res->content;

$your_app->handle_resource($resource);

DESCRIPTION

This module helps you to build OAuth Consumer application.

METHODS

new(%args)

parameters

consumer_key

consumer_key value

consumer_secret

consumer_secret value

signature_method

Signature method you can choose from 'HMAC-SHA1', 'PLAINTEXT', and 'RSA-SHA1' (optional, 'HMAC-SHA1' is set by default)

http_method

HTTP method (GET or POST) when the request is for request token or access token. (optional, 'POST' is set by default)

auth_method

OAuth::Lite::AuthMethod's value you can choose from AUTH_HEADER, POST_BODY and URL_QUERY (optional, AUTH_HEADER is set by default)

realm

The OAuth realm value for a protected-resource you wanto to access to. (optional. empty-string is set by default)

site

The base site url of Service Provider

request_token_path
access_token_path
authorize_path
callback_url

Site and other paths, simple usage.

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

If the authorization_url is run under another domain, for example.

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

Like this, if you pass absolute url, consumer uses them as it is.

You can omit site param, if you pass all paths as absolute url.

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},
);

And there is a flexible way.

# don't 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} );

# set authorize path here directly
my $url = $consumer->url_to_authorize(
    token        => $rtoken, 
    url          => q{http://www.example.org/authorize},
    callback_url => q{http://www.yourservice/callback},
);

# set access token url here directly
my $atoken = $consumer->get_access_token( url => q{http://api.example.org/access_token} );

So does callback_url. You can set it on consutructor or url_to_authorize method directly.

my $consumer = OAuth::Lite::Consumer->new(
    ...
    callback_url => q{http://www.yourservice/callback},
);
...
my $url = $consumer->url_to_authorize( token => $request_token );

Or

my $consumer = OAuth::Lite::Consumer->new(
    ...
);
...
my $url = $consumer->url_to_authorize(
    token        => $request_token,
    callback_url => q{http://www.yourservice/callback},
);

request_token_url

access_token_url

authorization_url

url_to_authorize(%params)

parameters

url

authorization url, you can omit this if you set authorization_path on constructor.

callback_url

Url which service provider redirect end-user to after authorization. You can omit this if you set callback_url on constructor.

token

request token value

my $url = $consumer->url_to_authorize(
    url          => q{http://example.org/authorize}, 
    token        => $request_token,
    callback_url => q{http://www.yousrservice/callback},
);

get_request_token(%params)

Returns a request token as an OAuth::Lite::Token object.

parameters

url

Request token url. You can omit this if you set request_token_path on constructor

realm

Realm for the resource you want to access to. You can omit this if you set realm on constructor.

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;

get_access_token(%params)

Returns a access token as an OAuth::Lite::Token object.

parameters

url

Request token url. You can omit this if you set request_token_path on constructor

realm

Realm for the resource you want to access to. You can omit this if you set realm on constructor.

token

Request token object.

my $token = $consumer->get_access_token(
    url   => q{http://api.example.org/request_token}, 
    realm => q{http://api.example.org/picture},
    token => $request_token,
) or die $consumer->errstr;

say $token->token;
say $token->secret;

gen_oauth_request(%args)

Returns HTTP::Request object.

my $req = $consumer->gen_oauth_request(
    method  => 'GET', 
    url     => 'http://example.com/',
    headers => [ Accept => q{...}, 'Content-Type' => q{...}, ... ],
    content => $content,
    realm   => $realm,
    token   => $token,
    params  => { file => 'mypic.jpg', size => 'small' },
);

request(%params)

Returns HTTP::Response object.

parameters

realm

Realm for a resource you want to access

token

Access token OAuth::Lite::Token object

method

HTTP method.

url

Request URL

parmas

Extra params.

content

body data sent when method is POST or PUT.

my $response = $consumer->request(
    method  => 'POST', 
    url     => 'http://api.example.com/picture',
    headers => [ Accept => q{...}, 'Content-Type' => q{...}, ... ],
    content => $content,
    realm   => $realm,
    token   => $access_token,
    params  => { file => 'mypic.jpg', size => 'small' },
);

unless ($response->is_success) {
    ...
}

find_realm_from_last_response

gen_auth_header($http_method, $request_url, $params);

parameters

realm

realm for a resource you want to access

token

OAuth::Lite::Token object(optional)

my $header = $consumer->gen_auth_header($method, $url, {
    realm => $realm,
    token => $token,
});

gen_auth_query($http_method, $ruqest_url, $token, $extra)

gen_auth_params($http_method, $request_url, [$token])

Generates and returns all oauth params.

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};

If you pass token as third argument, the result includes oauth_token value.

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};

oauth_request

oauth_req

Returns last oauth request.

my $req_token = $consumer->get_request_token(...);
say $consumer->oauth_request->uri;

my $req_token = $consumer->get_access_token(...);
say $consumer->oauth_request->uri;

oauth_response

oauth_res

Returns last oauth response.

my $req_token = $consumer->get_request_token(...);
say $consumer->oauth_response->status;

my $req_token = $consumer->get_access_token(...);
say $consumer->oauth_response->status;

oauth_clear

remove last oauth-request and oauth-response.

AUTHOR

Lyo Kato, lyo.kato _at_ gmail.com

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.