What is oAuth?

OAuth is an open protocol that allows users to share their protected resources (e.g. photos, videos, contact lists) stored on one site with another site without having to hand out their username and password.

What Can My Application Access With oAuth?

With oAuth support, your application can now access the information provided by several websites. For example, here is an abbreviated list of services and links to their developer documentation.

Site	Documentation Link
Photobucket	http://photobucket.com/developer/
SmugMug	http://wiki.smugmug.net/display/SmugMug/API
Twitter	https://dev.twitter.com/
88 Miles	http://www.88miles.net/pages/developers
Meetup.com	http://www.meetup.com/meetup_api/docs/
OpenSocial	http://opensocial.org/Technical-Resources
Yammer	http://developer.yammer.com/
Netflix	http://developer.netflix.com/docs/Security
TripIt	http://www.tripit.com/developer
Mr. Number	http://skydeck.com/developer/docs

How Do I Add oAuth To My Application?

To add oAuth to your application, you'll need to collect some information about the protected resource you intend to access:

Information	Description
GET or POST Verb	Find out which method the site uses to transfer oAuth data to and from the server. If you aren't sure, just leave the selection as "GET".
Application Key	Also known as the consumer key, or public key. This information will typically be a string of letters and numbers.
Secret Key	Also known as the consumer secret, or private key. This information will also typically be a string of letters and numbers. Keep this key a secret. It should never be human-readable in your applications. The appMobi cookie structure (AppMobi.cache.setCookie) saves data to the device in an encrypted fashion.
Request Token Endpoint	The URL for the appMobi application to use to request a token from the data provider.
Authorize Endpoint	The URL for the appMobi application to open so that the user may enter their username and password to get access to the data provider.
Access Token Endpoint	The URL for the appMobi application to use to get the response from the data provider.
Callback URL	This is the URL loaded following the authorization process. This URL should always be set to http://127.0.0.1 in order to call back to the appMobi application directly.

Once you have the oAuth information for your data, enter it into the XDK for the application. Click on the oAuth icon ( )on the left-hand side of the XDK. That should bring up an informational page about the oAuth service. Click the "Go" button to register the application.

You will be taken to the Control Center page in appHub. Expand the application for which you wish to configure oAuth. Next, select the Credentials icon contained in the App Development Tools section

The next page should give you a place to enter oAuth data for your application. Click “Add” to add the data you just collected.

Choose a service name to describe the oAuth data set you are entering, and fill in the remaining fields with the information from above.

Testing oAuth in the XDK and on Device

Once your application has been registered to use oAuth, you'll want to add the appropriate commands to read the information from the protected resource.

Get Authorization from the Resource

The first thing your application will have to do is get authorization from the protected resource. The application will automatically display the appropriate web-based sign on screen for the protected resource. Once the application's user has entered the appropriate credentials, or in the case that the authorization was rejected, the application will throw an appMobi.oauth.protected.data event signaling that data has arrived back from the protected resource.


document.addEventListener("appMobi.device.ready",function(){
	var parameters = new AppMobi.OAuth.ProtectedDataParameters();
	parameters.service = 'Twitter1';
	parameters.url = 'https://api.twitter.com/1/account/verify_credentials.xml';
	parameters.id = 'tweet_get';
	AppMobi.oauth.getProtectedData(parameters);
},false);

Handle the Authorization Response from the Resource

This code will handle any data response from the protected resource. Depending on the resource and what the application is trying to achieve, the object returned from this event could hold various types of information. This is where the application developer would consume any data that was returned.


document.addEventListener("appMobi.oauth.protected.data",function(evt){
	if (evt.id == "tweet_get")
	{
		AppMobi.notification.alert("Twitter Authorization Obtained","OK");
	}
	if (evt.id == "tweet_update")
	{
		AppMobi.notification.alert("Twitter Updated","Success","OK");
	}
},false);

Make Requests to the Protected Resource

Once your application has successfully gotten authorization from the protected resource, it is ready to access those resources using the AppMobi.oauth.getProtectedData command. Here is an example function that posts an update to a Twitter account.


function UpdateTwitter(strStatusUpdate)
{
	var status = "status=" + strStatusUpdate;
	var parameters = new AppMobi.OAuth.ProtectedDataParameters();
	parameters.service = 'Twitter1';
	parameters.url = 'https://api.twitter.com/1/statuses/update.xml';
	parameters.id = 'tweet_update';
	parameters.method = 'POST';
	parameters.body = status;
	AppMobi.oauth.getProtectedData(parameters);
}