The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-OAuth-Simple-1.1
River stage one • 5 direct dependents • 7 total dependents
1 ++
/ Net::OAuth::Simple

NAME

Net::OAuth::Simple - a simple wrapper round the OAuth protocol

SYNOPSIS

First create a sub class of Net::OAuth::Simple that will do you requests for you.

    package Net::AppThatUsesOAuth;

    use strict;
    use base qw(Net::OAuth::Simple);


    sub new {
        my $class  = shift;
        my %tokens = @_;
        return $class->SUPER::new( tokens => \%tokens, 
                                   urls   => {
                                        authorization_url => ...,
                                        request_token_url => ...,
                                        access_token_url  => ...,
                                   });
    }

    sub view_restricted_resource {
        my $self = shift;
        my $url  = shift;
        return $self->make_restricted_request($url, 'GET');
    }

    sub update_restricted_resource {
        my $self         = shift;
        my $url          = shift;
        my %extra_params = @_;
        return $self->make_restricted_request($url, 'POST', %extra_params);    
    }
    1;

Then in your main app you need to do

    # Get the tokens from the command line, a config file or wherever 
    my %tokens  = get_tokens(); 
    my $app     = Net::AppThatUsesOAuth->new(%tokens);

    # Check to see we have a consumer key and secret
    unless ($app->consumer_key && $app->consumer_secret) {
        die "You must go get a consumer key and secret from App\n";
    } 
    
    # If the app is authorized (i.e has an access token and secret)
    # Then look at a restricted resourse
    if ($app->authorized) {
        my $response = $app->view_restricted_resource;
        print $response->content."\n";
        exit;
    }


    # Otherwise the user needs to go get an access token and secret
    print "Go to ".$app->get_authorization_url."\n";
    print "Then hit return after\n";
    <STDIN>;

    my ($access_token, $access_token_secret) = $app->request_access_token;

    # Now save those values

Note the flow will be somewhat different for web apps since the request token and secret will need to be saved whilst the user visits the authorization url.

For examples go look at the Net::FireEagle module and the fireeagle command line script that ships with it. Also in the same distribution in the examples/ directory is a sample web app.

METHODS

new [params]

Create a new OAuth enabled app - takes a hash of params.

One of the keys of the hash must be tokens, the value of which must be a hash ref with the keys:

consumer_key
consumer_secret

Then, when you have your per-use access token and secret you can supply

access_token
access_secret

Another key of the hash must be urls, the value of which must be a hash ref with the keys

authorization_url
request_token_url
access_token_url

authorized

Whether the client has the necessary credentials to be authorized.

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

signature_method [method]

The signature method to use.

Defaults to HMAC-SHA1

tokens

Get all the tokens.

consumer_key [consumer key]

Returns the current consumer key.

Can optionally set the consumer key.

consumer_secret [consumer secret]

Returns the current consumer secret.

Can optionally set the consumer secret.

access_token [access_token]

Returns the current access token.

Can optionally set a new token.

access_token_secret [access_token_secret]

Returns the current access token secret.

Can optionally set a new secret.

general_token [token]

Get or set the general token.

See documentation in new()

general_token_secret [secret]

Get or set the general token secret.

See documentation in new()

authorized_general_token

Is the app currently authorized for general token requests.

See documentation in new()

request_token [request_token]

Returns the current request token.

Can optionally set a new token.

request_token_secret [request_token_secret]

Returns the current request token secret.

Can optionally set a new secret.

authorization_url

Get the url the user needs to visit to authorize as a URI object.

Note: this is the base url - not the full url with the necessary OAuth params.

request_token_url

Get the url to obtain a request token as a URI object.

access_token_url

Get the url to obtain an access token as a URI object.

request_access_token

Request the access token and access token secret for this user.

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

Returns the access token and access token secret but also sets them internally so that after calling this method you can immediately call location or update_location.

request_request_token

Request the request token and request token secret for this user.

This is called automatically by get_authorization_url if necessary.

get_authorization_url [param[s]]

Get the URL to authorize a user as a URI object.

If you pass in a hash of params then they will added as parameters to the URL.

make_restricted_request <url> <HTTP method> [extra[s]]

Make a request to url using the given HTTP method.

Any extra parameters can be passed in as a hash.

make_general_request <url> <HTTP method> [extra[s]]

Make a request to url using the given HTTP method using the general purpose tokens.

Any extra parameters can be passed in as a hash.

load_tokens <file>

A convenience method for loading tokens from a config file.

Returns a hash with the token names suitable for passing to new().

Returns an empty hash if the file doesn't exist.

save_tokens <file> [token[s]]

A convenience method to save a hash of tokens out to the given file.

GOOGLE'S SCOPE PARAMETER

Google's OAuth API requires the non-standard scope parameter to be set in request_token_url, and you also explicitly need to pass an oauth_callback to get_authorization_url() method, so that you can direct the user to your site if you're authenticating users in Web Application mode. Otherwise Google will let user grant acesss as a desktop app mode and doesn't redirect users back.

Here's an example class that uses Google's Portable Contacts API via OAuth:

    package Net::AppUsingGoogleOAuth;
    use strict;
    use base qw(Net::OAuth::Simple);

    sub new {
        my $class  = shift;
        my %tokens = @_;
        return $class->SUPER::new(
            tokens => \%tokens, 
            urls   => {
                request_token_url => "https://www.google.com/accounts/OAuthGetRequestToken?scope=http://www-opensocial.googleusercontent.com/api/people",
                authorization_url => "https://www.google.com/accounts/OAuthAuthorizeToken",
                access_token_url  => "https://www.google.com/accounts/OAuthGetAccessToken",
            },
        );
    }

    package main;
    my $oauth = Net::AppUsingGoogleOAuth->new(%tokens);

    # Web application
    $app->redirect( $oauth->get_authorization_url(oauth_callback => "http://you.example.com/oauth/callback") );

    # Desktop application
    print "Open the URL and come back once you're authenticated!\n",
        $oauth->get_authorization_url;

See http://code.google.com/apis/accounts/docs/OAuth.html and other services API documentation for the possible list of scope parameter value.

RANDOMNESS

If Math::Random::MT is installed then any nonces generated will use a Mersenne Twiser instead of Perl's built in randomness function.

BUGS

Non known

DEVELOPERS

The latest code for this module can be found at

    https://svn.unixbeard.net/simon/Net-OAuth-Simple

AUTHOR

Simon Wistow, <simon@thegestalt.org >

BUGS

Please report any bugs or feature requests to bug-net-oauth-simple at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-OAuth-Simple. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::OAuth::Simple

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2009 Simon Wistow, all rights reserved.

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