API Reference

Using OAuth to Integrate with Other Web Services

Acre provides special OAuth APIs for its apps to act securely on the user's behalf against external web services and then integrate your Acre app seamlessly with them.

Mini Intro to OAuth

If you already know about OAuth you can safely skip this section, otherwise it might help if you read on.

First of all, unlike most people might think, the 'auth' part of OAuth stands for 'authorization' and not 'authentication'. OAuth allows a user to 'authorize' an application to act on her behalf against another web service, but without revealing her username/password to the application. It has nothing to do with the user identity or how the user authenticates herself with the web service provider she wants the app to use on her behalf.

One standard example is a social network site asking you for your web mail password as a way to get a list of your contacts: you have to trust that the social network site not to abuse those credentials you give. With OAuth, you can authorize the app to act on your behalf but only to do particular tasks and nothing else (for example, you can allow the app to read your contacts, but not read your email or delete it).

The best metaphor to describe what OAuth does is the concept of a 'valet key': some fancy cars come with this notion of a valet key, a car key that you give to the guy at the restaurant that parks your car. This key allows the valet person to drive the car only for a certain distance, after which it shuts the car down and calls you.

OAuth is basically a way to obtain and give your application a 'valet key' so that it can act on your behalf (like the valet driver) against some web service, instead of you having to give you the entire key (your username/password pair).

Acre uses OAuth to obtain a 'valet key' for your app from Freebase and allow your app to write on Freebase on your behalf.

OAuth in Acre

Acre tries to allow you to use OAuth without having you to learn its inner workings or what goes on behind the scenes of the protocol.

Here is simply what you have to do:

  1. register your application with the OAuth service provider and obtain the token/secret pair that identifies your application
  2. obtain the OAuth URLs of the web service you want to call (don't worry, Acre gives you a registry of some known OAuth providers that you can use just by referring to, for example Freebase, Google, Yahoo!, Twitter etc..)
  3. pass the above information to Acre to obtain your OAuth 'access token' (which is your 'valet key')
  4. call the oauth-enabled URL like you normally would with the acre api (acre will transparently fetch the access token from your cookies and use it to wrap your call via OAuth)

Phase 1: register your application with the OAuth provider

The OAuth spec does not specify how this phase is performed, which means that each OAuth provider will probably do it differently, so look for their OAuth documentation on how to do this.

Once you have obtain the token/secret pair form the OAuth provider, click on the name of your App at the very top of the app editor, on the left hand side, and use the 'web services' tab of the drop down dialog to add the token/secret pair to your app.

The 'service domain' field should contain the host part of the URLs that will be OAuth enabled (for example, twitter.com if you're connecting to Twitter)

Note that you have to do this only once per app and per OAuth provider your app uses.

Phase 2: obtain the OAuth provider URLs

In Acre, an OAuth service provider is a javascript object with this shape:

var oauthProvider = {
  domain                 : "freebase.com",
  request_token_URL      : "https://api.freebase.com/api/oauth/request_token",
  access_token_URL       : "https://api.freebase.com/api/oauth/access_token",
  user_authorization_URL : "https://www.freebase.com/signin/authorize_token"
};

the 'domain' indicates that this OAuth provider is responsible for the URLs in that domain (similar to how cookies work); the other three properties are the three URLs that identify the provider's own OAuth services.

The Acre API contains a registry of well known OAuth providers (acre.oauth.providers), including Google and Yahoo!. You can call use console.log(acre.oauth.providers) to obtain a browsable list of them from your app console.

If the Acre registry doesn't know your OAuth provider, you have to find that information and come up with that object yourself.

NOTE: if your app will use OAuth to write on Freebase, this phase is optional and you can safely skip it since Acre already know about Freebase's URLs as an OAuth provider.

Phase 3: obtain the OAuth access token

Before you call a oauth-enabled web service, you need to obtain the app credentials to act on the behalf of the user (the 'valet key' we talked about above). This involves a complicated dance of page redirects and cryptographic signing, but the the Acre OAuth API does all this for you transparently and sets the obtained OAuth access token in the user's cookies.

To do this simply call 

acre.oauth.get_authorization(oauthProvider);

where 'oauthProvider' is the object you obtained in the previous phase.

The call does not return anything, but it interrupts your regular application flow to perform the OAuth authorization dance, or throw an exception in case something went wrong. Once the OAuth dance is completed, the OAuth access token will be stored in the user cookies and the application flow will continue pass the call.

WARNING: because of the way acre.exit() works by throwing a special exception to interrupt the application flow before the end of the script, a try/catch around acre.oauth.get_authorization must re-throw those special acre.exit() exceptions after catching them or the entire OAuth dance won't be performed. Here is some code to do that:

try {
  ...
  acre.oauth.get_authorization(...)
  ...
} catch (err if (err.message != "acre.exit")) {
  ...
}

NOTE: if you call "acre.oauth.get_authorization()" without passing an oauthProvider, that call will default to Freebase as the OAuth provider.

Phase 4: call the OAuth-enabled web service

Once the user has the OAuth access token setup as their cookies, Acre can make web service requests with OAuth.

In order to do this, you have to set the "sign" parameter of acre.urlfetch to true for urlfetch to transparently use OAuth to sign and authorize your request. Freebase-specific write calls like acre.freebase.mqlwrite and acre.freebase.upload use OAuth transparently if the user has been authorized.

Example of Use

Let's tie everything together with an example:

acre.oauth.get_authorization(acre.oauth.providers.twitter)
var result = acre.urlfetch("http://twitter.com/...",GET,null,null,true);

yeah, it's that simple.

Developer Tools: