Update 2 See this post or just skip straight to this excellent library for all of your OAuth and Java needs

*Update* The code in this entry no longer works with the Android SDK because of the upgrade to HttpClient 4. The OAuth Java library has been updated to work with HttpClient 4 but I have not looked at it recently *Update*
Fire eagle is a Yahoo! location sharing service that provides an API that allows external clients and services to update and query user location information. Besides the obvious interesting connection between a location sharing service and Android’s Location-Based-Services API, I became more interested in how fire eagle uses OAuth as it’s authorization scheme and how it can be used on a smart mobile device.

OAuth is an open authentication protocol that allows access to web service resources from other web services as well as desktop applications. Other open authentication schemes, like OpenID, use http redirects and require users input credentials onto a web page in order to authorize clients. This isn’t very useful for a desktop or mobile client that would like direct access to a web API. OAuth still requires the user to enter their credentials into a website, but this is only done during the initial application authorization step, after that step is complete the application can make authorized API calls directly without needing user intervention.

A web service that uses OAuth will let application developers to register for a consumer key which is paired with a consumer secret. The consumer key is used to identify the client application and the consumer secret is used to sign requests made by the client application which is then verified by the host web service.

Here is a general outline of the OAuth process from a client application’s perspective:
1. The client requests a request token from the service. They include their consumer key and a few other OAuth specific parameters including a hash signature using the consumer secret.The service replies with a request token.
2. The client application then directs the user to the service’s authorization page, with the request token as a parameter, where the user can log into the service and authorize the application to access their information.
3. Once the user is finished authorizing, the client application needs to request an access token which will be used to make authorized calls to the service’s API. The service replies to the request with an access token and access secret. The application needs to save both of these securely.
4. The client application can now make API calls by including the user’s access token, and signing the oauth parameters with the access secret.

Laserbeak
I am going to attempt to walk through a “simple” android application that performs the request and authorization steps of OAuth as well as makes an update call to fire eagle with the current location of the phone.

Setup
The first step will be getting your own application key and secret token from the fireeagle service. Fire eagle is currently invite-only but there are plenty of invites floating around.

The second step is to setup a new android project and give it GPS and LOCATION permissions.

The third step will be getting the OAuth java libraries from the OAuth Java repository. Since the libraries use the apache-commons and http libraries that are already included in android you can simply drop the net.oauth, net.oauth.client, and net.oauth.signature into your source directory. Note: The OAuth java libraries aren’t “finished” and not as well documented as the libraries for other languages but I have found them to be fairly straight forward and functional.

The Application
We will create a simple application that consists of an activity with three buttons. Each button’s onClick event will trigger a step in our authorization process. Complete source code for this activity can be found here

Initializing the OAuth provider, consumer, and accessor in the Activity’s OnCreate method:

		serviceProvider = new OAuthServiceProvider(OAUTH_REQUEST,
				OAUTH_AUTHORIZE, OAUTH_ACCESS);

		consumer = new OAuthConsumer("http://www.noredirectfordesktop.com",
				CONSUMER_KEY, CONSUMER_SECRET, serviceProvider);

		accessor = new OAuthAccessor(consumer);

		httpClient = new OAuthHttpClient(new HttpClientPool() {

			public HttpClient getHttpClient(URL server) {
				return new HttpClient();
			}
		});

Here we initialize the classes that will be used to make OAuth requests to the Fire eagle service, we include the three URLs as well as the consumer key and consumer secret. All of the OAuth specific parameters and operations will be performed by these classes.

The request token button:

Button requestButton = (Button) this.findViewById(R.id.req_button);
		requestButton.setOnClickListener(new OnClickListener() {

			public void onClick(View arg0) {

				try {
					httpClient.getRequestToken(accessor);
				} catch (Exception e) {
					// TODO Auto-generated catch block
					e.printStackTrace();
				}

				// manually set the access token to the request token...not sure
				// why
				accessor.accessToken = accessor.requestToken;

				// start browser application so user can authorize your
				// application
				Intent authIntent = new Intent(Intent.VIEW_ACTION);
				authIntent.setData(Uri.parse(FIRE_EAGLE_AUTHORIZE_URL
						+ accessor.requestToken));
				Laserbeak.this.startActivity(authIntent);
			}

		});

Here we use the built in getRequestToken method to make a token request to the service. If all goes well the token is stored in the requestToken field of the accessor, for the authorization step we need to manually set the accessToken field on the accessor to equal the requestToken.
The next step is interesting in that we need to have the user manually authorize our application, android makes it easy to launch the browser to the authorization URL using a VIEW_ACTION intent. This will launch a browser that the user can use and once they are finished they can simply close the browser and return to the application which is still running in the background.

The authorize button:

Button authButton = (Button) this.findViewById(R.id.auth_button);
		authButton.setOnClickListener(new OnClickListener() {

			public void onClick(View arg0) {

				try {

					OAuthResponseMessage response = (OAuthResponseMessage) httpClient
							.invoke(accessor.newRequestMessage("GET",
									serviceProvider.accessTokenURL, null));

					// manually set these fields on the accessor from the
					// response
					accessor.accessToken = response.getParameter("oauth_token");
					accessor.tokenSecret = response
							.getParameter("oauth_token_secret");

					//at this point you should store the accessToken and tokenSecret
					//somewhere secure
				} catch (Exception e) {
					e.printStackTrace();
				}
			}

		});

Our application is now authorized to make API calls, lets try calling update with the current Lat/Lon of our phone

Button updateButton = (Button) this.findViewById(R.id.update_button);
		updateButton.setOnClickListener(new OnClickListener() {

			public void onClick(View arg0) {

					// get current location and use it as params to our API call
					LocationManager locMan = (LocationManager) Laserbeak.this
							.getSystemService(Context.LOCATION_SERVICE);
					Location loc = locMan.getCurrentLocation("gps");

					HashMap params = new HashMap();
					params.put("lat", loc.getLatitude());
					params.put("lon", loc.getLongitude());
					try {

						OAuthResponseMessage response2 = (OAuthResponseMessage) httpClient
								.invoke(accessor.newRequestMessage("POST",
										FIRE_EAGLE_UPDATE_URL, params
												.entrySet()));
					} catch (Exception e) {
						e.printStackTrace();
					}

			}
		});

Here we get the LocationManager and get the user’s current latitude and longitude and put them in a parameter map to be used in the request.

Those are the basic steps for using OAuth and fire eagle. There are a number of things I left out like saving and accessing the access token and access secret from a secure place, as well as saving the state of the accessor for when your application gets interrupted by an incoming call. You could also create a service that updates your location periodically in the background instead of explicitly updating it in an activity.

Unfortunately due to security issues, desktop and mobile applications are only allowed to access the user and update API calls. The more interesting calls that allow you to query all the users of your application and create a social location network are restricted to web applications.

Now that you know how to authorize an application in OAuth you can use the above steps to interact with any other OAuth capable API, like pownce.