OAuth.pmod

In short OAuth is a method for API authorization without you giving away your username and password — OAuth uses a signature based authentication model. Twitter and a lot of the web service API:s from Google – amongst others – use OAuth for authorization when using their API:s.

If you want to know more about OAuth read up on the official site or on Wikipedia.

Enough of this jibberish…

Using OAuth.pmod

First of all you need some service provided that uses OAuth for authorization, of course. Once you’ve registered an application at a service provider, like Google or Twitter, you will get an application key or consumer key as it’s also called, and an application secret or also called consumer secret. They can look like:

// NOTE: These values are fictional
Consumer key: 42mngF1XrTRvUxeKYsNJ2Q
Consumer secret: yDGp2M0CRgP82rxInWZQaKAJ6ATqugcaMJbe42h5Tls

The consumer key and consumer secret are specific for a given application, regardless of the user using the application.

Consumer and Token

In all calls to an OAuth service we need a Consumer and a Token. The Consumer is always the same, but the Token will change during the authorization chain.

OAuth.Consumer = OAuth.Consumer(consumer_key, consumer_secret);
OAuth.Token token = OAuth.Token(0, 0);

// Later down the chain, as an example
token->key = my_access_token;
token->secret = my_access_token_secret;

Authorization

In short the authorization process goes like this:

1. Request a request_token
2. Redirect the user to the login page – with the request_token as a query string variable – at the service providers site
3. The user allows the application to access its account.
4. The service provider redirects the user – with a new token/PIN-code, depending on the specific implementation and whether it’s a web, desktop or mobile application – as a query string variable.
5. The token/PIN is then used to request an access_token.
6. Hopefully the authentication worked out just fine.

Parameters

We need to send parameters to the OAuth service we’re using, and there are two classes related to this: Params which is a collections of Param. This is how it works:

OAuth.Param param1 = OAuth.Param("name1", "value1");
OAuth.Param param2 = OAuth.Param("name2", "value2");

// Make a collection of the parameters
OAuth.Params params = OAuth.Params(param1, param2);

// Append another parameter to the collection
params += OAuth.Param("name3", "value3");

Communicating with a service

There’s basically only one method, request(), in the module you need to use:

OAuth.Request request = OAuth.request(service_url, consumer, token [, params, http_method]);
// Now we need to sign the request with the desired method. 
// NOTE: Only HMAC/SHA1 is supported
request->sign(OAuth.Signature.HMAC_SHA1, consumer, token);

// Now we're ready to send the request
// submit() takes an optional mapping as argument which will be added to the HTTP headers
Protocols.HTTP.Query q = request->submit();

if (q->status != 200)
  error("Bad HTTP response\n");

// The result from the OAuth service. Most certainly in the form of a query string.
string data = q->data();

The class Social.Twitter implements an OAuth authorization, so look at that class for an example of usage.