OAuthSimple

 

A simple, common platform for signing OAuth requests. Currently available in Perl, Python, Javascript and PHP. More to come.

 

Introduction

OAuth is fairly easy, unfortunately, the documentation isn't and the majority of libraries were written mostly as products of experimentation rather than utility. OAuthSimple is designed to be simple. Use it to sign requests for services requiring OAuth validation. If you want anything more than that, I suggest you look at the other, richer, far more capable libraries out there.

 

Examples

The easiest way to call OAuthSimple is to create an object and then call the “sign” method passing a hash of values. This differs a bit from language to language, but I've tried to stay true as much as possible.

 

In Javascript:

var result = OAuthSimple().sign({path:'http://example.com/rest',

       parameters: {foo:'bar', bleck:'gorp'},

                            signatures: {consumer_key:'abcd1234',

 shared_secret:'abc123'}});

The value of “result.signed_url” contains the full, signed URL to use.

 

In PHP:

$oauth = new OAuthSimple();

$result = $oauth->sign(Array(path=>'http://example.com/rest',

parameters=>Array('foo'=>'bar', 'bleck'=>'gorp'),

signatures=>Array('consumer_key'=>'abcd1234',

  'shared_secret'=>'abc123')));

The value of “$result->signed_url” contains the full, signed URL to use.

 

(starting to see a pattern here?)

 

Reference:

General:

var args = 'fruit=orange&fruit=banana&number=1&string=foo';

var args = {fruit: [orange,banana],

number: 1,

string: 'foo' };

By Use:

OAuthSimple ([(string)Consumer_key ,(strng) Shared_Secret])  

This is the object constructor. Arguments are optional.

Consumer_Key (sometimes called the API_Key) and Shared_Secret are values provided to you at the time of registration with the OAuth site you wish to talk to. They're usually long, complex bunches of letters and numbers that look a bit like what happens when your keyboard is being eaten by a bear. While you do not need to specify them in this initial call, you must specify them before you can validly sign a URL. OAuthSimple will throw an exception if the values are not present.

This will return an initialized object.

sign([(hash) parameters])

This method will return a hash of valid, signed elements.

The parameters are optional, but can contain the following:

path: The URI to call (e.g. “ http://example.com/rest/ ”)

parameters: The parameters to use for this call (see General Reference regarding parameters)

signatures: a hash of the signature pairs to use.

consumer_key & shared_secret are required for all calls.
access_token & token_secret are only required for “elevated” calls.

In addition, the following optional elements can also be specified:

action :The HTTP Method to use (GET, POST, DELETE, etc.)

method : the method to use to sign the URL (currently only PLAINTEXT or the default, HMAC-SHA1)

The returned hash contains the following:

header : an HTTP Authorization header content string. Note: This does NOT include the “Authorization:” prefix since various systems have various means to render that.

parameters : a deconstructed hash of the parameters

signature: the OAuth signature value

signed_url : the fully qualified, signed url created from the method, path and parameters.

getHeaderString( [(hash) $parameters] )

return a valid HTTP Authorization header content string.

See .sign() for a description of the arguments.

setParameters ([ hash or string] $URLParameters )

setQueryString([ hash or string] $URLParameters )

Set the URL parameters for this call (See “general” for a discussion of parameters)

returns the current object.

setURL( (string)$path )

setPath( (string)$path )

Set the URL path (everything up to the “?” in a given URL.)

setAction( [(string) $action] )

Set the HTTP action to take. Action must be alphabetic. If no action is specified, the Action is set to “GET”.

setSignatureMethod ( [(string) $method] )

Set the OAuth Signature Method, (currently restricted to either PLAINTEXT or HMAC-SHA1). If no method is specified, the method is set to “HMAC-SHA1”.