Getting started
Building a Fire Eagle consumer with OAuth.net
OAuth.net is a .net library
See the demo: Where Am I?
Get the source: oauth-dot-net project on Google Code
Fire Eagle is a location broker: it allows you to share your physical location with applications. For example, when on holiday a GPS-enabled mobile phone could periodically push your location to Fire Eagle. A Fire Eagle-enabled holiday guide could then send you tips about local attractions, places to eat and things to do in your vacinity.
While this example sounds quite innocuous, some people naturally have concerns about sharing their location on the Internet. As such, Fire Eagle gives the user fine-grained control of their data, allowing the user to choose how precisely their location should be shared with each application, if at all, and whether that application can update their location. The user can also choose to go temporarily silent at any time. Although Fire Eagle could form part of a social network, it itself does not have any social features—for example, you cannot view other people's locations via the Fire Eagle website.
Fire Eagle's interface, then, is a programmatic one: its API. As with most APIs, it relies on secure authentication and authorization, and it uses OAuth for this.
OAuth
OAuth is an emerging standard for handling third-party authentication and authorization for protected resources, for example APIs. Previously, many vendors have devised their own, incompatible, authentication schemes for their APIs. OAuth is a standard which draws upon many of these existing API authentication schemes: Google AuthSub, AOL OpenAuth, Yahoo BBAuth, Upcoming's API, Flickr's API and Amazon Web Services API.
The key tenet of these schemes and of OAuth is that users should be able to share their data with third-party applications without sharing their passwords.
By standardising these similar but different schemes into OAuth, the OAuth team has made it easier to produce both new APIs (service providers) and also consumer applications for these APIs.
At Madgex, we've developed an OAuth library for .NET called OAuth.net. The library hides many of the implementation details of OAuth to make it even easier for .NET developers to build OAuth-enabled consumers and service providers.
Fire Eagle Consumer Demo
To demo how to build a consumer web application using OAuth.net, I've built a mashup of Fire Eagle and Google Maps using OAuth.net, which displays your last known location on a map and allows you to update your location.
To use the demo, you will need a Fire Eagle account. When you visit the demo site, you will first be asked to log in to Fire Eagle and allow OAuth.Net Fire Eagle demo to access and update your location. You will then be directed to the mashup on our servers, which can fetch and update your location, without you having given us your password.
Speaking to Fire Eagle
To get a user's location, the application needs to make a request to the user API URL (GET https://fireeagle.yahooapis.com/api/0.1/user). This should return an XML document containing the user's location hierarchy, from which it will pick the best-guess location to display on the map:
// Find the user's location var request = OAuthRequest.Create( new Uri("https://fireeagle.yahooapis.com/api/0.1/user"), FireEagle.GetService, context.Session["request_token"] as IToken, context.Session["access_token"] as IToken); OAuthResponse response = request.GetResource();
The OAuthRequest object is entirely responsible for handling OAuth authentication of a request. When creating an OAuth request, you pass in the URL of the protected resource to access, the OAuth service definition and, optionally, request or access tokens that have previously been obtained.
The OAuthService object encapsulates the protocol configuration details (its request token, authorization & access token URLs, the HTTP method to use, whether to use headers, the authentication realm, the signature method to sign request with and the protocol version) and the consumer's key and secret. OAuth does not yet have a discovery specification so the developer must configure these by hand (there are default values for most values).
Tokens
Authenticating via OAuth involves the issuing of two tokens: the request token and the access token. Briefly, a request token allows a consumer to request access to resource(s). The user must then authorize the request on the service provider website. Once a request token has been authorized by the user, it can be swapped for an access token, which gives access to the particular resource(s).
This is somewhat akin to staying at an all-inclusive hotel: on arrival, you tell the bellboy you would like to check in and are taken to the reception desk (compare this to obtaining a request token). Here, your details are checked against your passport (authentication) and the bookings (authorization) and you are issued with a wristband (access token). This wristband signifies to the staff that you are allowed to use the all-inclusive facilities, avoiding the need to constantly prove your identity and entitlement.
Once an access token is obtained, it can usually be used for future requests without obtaining new request tokens or repeating the authorization process. Likewise, your wristband can be used on any number of occasions during your stay. Access tokens (wristbands) may have a lifetime, after which they are revoked or expired (such as at check-out) and will no longer grant access to resources. Similarly, they could be temporarily revoked (the bar is shut during the night), or give different consumers different levels of access (children could have different colour wristbands so bar staff know not to serve them alcohol).
Authorization
The demo application stores the user's request and access tokens in the user's session object. It loads these from the session when creating each OAuthRequest, but the tokens may not have been obtained yet (in which case they will be null).
The OAuthRequest knows that if the access token is null, it should look for an authorized request token. If the request token is also null or unauthorized, it knows to get a request token, ask the user to authorize it and ask for an access token before finally requesting the protected resource.
The process of authorizing a request token involves sending the user to the service provider's website. How this is achieved may vary from consumer-to-consumer and is heavily dependent on the environment. Web applications will typically redirect the user to the service provider (as the demo does). Desktop or mobile applications will probably open a browser and wait for the user to return. Since this process is not well-defined, OAuthRequest does not try to do anything clever when faced with a null or unauthorized request token; instead it bombs out, leaving it up to the consumer application to handle the task.
This means that the GetResource call may not actually fetch the desired resource. The consumer should check the OAuthResponse.HasProtectedResource property to see whether authorization is required:
if (response.HasProtectedResource) { // Process the protected resource } else { // Authorization is required context.Session["request_token"] = response.Token; throw new AuthorizationRequiredException() { AuthorizationUri = FireEagle.GetService.BuildAuthorizationUrl( response.Token, callback) }; }
If there is no protected resource, the consumer needs to send the user to authorize the request token. The request token is stored in the OAuthResponse.Token property, and the consumer should store this so that when the user returns the process can resume with the authenticated request token.
In the demo site, the authorization URI is built and wrapped in a custom exception type. The authorization URI must be built by the OAuthService, which encodes the token string and optionally a callback URI in the query string according to the OAuth spec. The demo site takes will either Response.Redirect to the authorization URI if the request is for Default.aspx or send the authorization URI in the JSON response if the request is a AJAX call.
When the user returns from authorization, the demo site procedes as before, except now there is an authenticated (hopefully) request token, so it should be possible to get an access token and access the protected resource.
Working with the Fetched Resources
When the consumer receives the protected resource it requested, it should first store the access token so that it can avoid re-authorization for subsequent requests. Once it has done this, it can access the protected resource via the ProtectedResource property of the response.
Protected resources are represented by OAuthResource objects, which present the same interface as HttpWebResponse. The payload of the response is read into memory as part of the OAuth processing to check for possible OAuth problem reports, and this memory stream is exposed by the same GetResponseStream method that HttpWebResponse offers. This means you interact with the response just as you would were it a simple HTTP request:
if (response.HasProtectedResource) { // Store the access token context.Session["access_token"] = response.Token; // Load the response XML XmlDocument responseXml = new XmlDocument(); responseXml.Load(response.ProtectedResource.GetResponseStream()); // Check the response status if (responseXml.SelectSingleNode("rsp/@stat").Value == "ok") return Location.Parse(responseXml.SelectSingleNode( "rsp/user/location-hierarchy/location[@best-guess='true']")); else return null; } else { // Send user to authorize request token }
Futher Resources
Hopefully you have enough information to start building OAuth-enabled consumer applications with OAuth.net. If you're looking for more information about OAuth, the OAuth website is a good place to start. There is also an OAuth mailing list frequented by the OAuth team. For OAuth.net questions, you can email the Madgex team at oauth-dot-net@madgex.com.