Fire Eagle : Developer

Developer Centre

Best Practices for OAuth with Fire Eagle

Fire Eagle supports multiple methods of OAuth authentication that we tentatively name ‘web’, ‘desktop’, ‘mobile’ and ‘plugin’. However, the power of modern development tools rather blurs those definitions. Techniques that naturally apply to ‘desktop’ environments can now be applied to mobile devices, so there are some new tricks that can really smooth out the authentication experience for your users.

This article was written mostly to address our recommended method of authenticating from Apple’s iPhone platform, but the technique applies equally to other devices, and we've tried to cover the major ones.

We're trying to ensure that users are only exposed to the safest way to disclose their location using OAuth. To do this, it's critical that a fundamental principal of browser-based authentication is followed; that the contexts of the third party application and the web service authentication remain separate. To allow users to grant trust to an application, they must perform the OAuth action within their web browser, not within the applications themselves. Otherwise, there is no way to verify the identity and authenticity of any page which asks for their username and password. Users must not ever enter their username and password into a third party application when a browser-based authentication API like OAuth is available.

  1. When your application needs to authorise with Fire Eagle, present your introduction as normal; explain what you will use their location for, suggest a level of disclosure that will let users get the most out of your service, then take them to their web browser to perform the OAuth action in a fully separate trust context.

  2. Modern software environments have a really neat way to automatically move contexts from your application, into the user’s browser for authentication, and then right back into your app, using x-protocol:// URL handlers.

    When the user hits your ‘Authorize Fire Eagle’ button, create your Fire Eagle authorisation URL in the user's standalone browser application, and include the additional query parameter oauth_callback=x-net-myapp://oauth-response/.

    We've compiled instructions below on how you can add this sort of URL handling to applications for popular operating systems.

  3. The user will be guided through auth in the safest manner. They will be kept aware that they must only enter their Yahoo! passwords directly into the Yahoo! website, only using the trusted environment of their web browser. However, this technique means that they will still be returned to your standalone application without any further manual intervention. It's not ‘seamless’; it is by design that the user must be aware they're using the real website and not a fake. They have to see the seams, but the contexts of your application and the browser are bridged cleanly and automatically by the operating system, making the overall user experience very smooth.

Operating Systems with limited multi-processing capabilities (such as the iPhone) can use this technique to smoothly bridge the gap between their application and the authentication and authorisation processes. More capable operating systems that maintain applications in the background can use this technique to smooth out and remove the ‘Click OK to continue’ step common in browser-based authentication in the past.

A very important ‘do not’

A powerful feature of many software platforms (including iPhone OS), is to embed a web rendering control directly into an application. WebKit, Trident or Gecko powered controls allows HTML, CSS and JavaScript to be rendered right inside the app, and allows remote pages to be displayed, similar to the behaviour of a web browser.

This is a really useful tool for many purposes, but we insist that you must not use embedded rendering controls to present the OAuth process with Yahoo! and Fire Eagle.

Whilst the intention is to provide a slick authentication experience, masking the Yahoo! and Fire Eagle authentication screens inside an embedded control breaks the trust contexts that OAuth encourages, and exposes our users a huge risk of phishing. Because the log-in pages are embedded, the user has no way to confirm that the page you’ve directed them to is genuine; there’s no padlock confirmation for secure HTTPS connections, and no URL bar to inspect the domain. Users are being encouraged to check for these cues as part of their routine, and being discouraged from ever entering their passwords directly into a third party application (be it in their web browser, or in standalone applications). This is to help them stay safe on the internet. Keeping auth steps inside the browser is vital for that effort to progress.

The browser is an environment that the user trusts, and an environment where that trust can be verified — URL bar, SSL indicators, anti-phishing tools and so forth. A third party application is not, and is an environment of more limited trust. As such, a user should only ever enter their web service passwords into their most trusted environment; the browser.

In short, this behaviour makes it possible for an application to fake the Yahoo! login page, with no way for the user to verify. Usernames and passwords could be stolen and in the case of Yahoo, that risk extends far beyond Fire Eagle; the user’s email, address book, IM, and more could all be compromised.

Remaining within a single application is a small benefit massively outweighed by the devastating cost of a successful phishing scam. We’re pushing for our users to become familiar using browser-based auth within the browser only, and we will reject applications which ask for user passwords directly.

How to Auth Right

Following are basic instructions on how to add custom URL handlers into your application, so that you can authenticate through the web browser, without your user manually switching between applications.

Register a custom URL handler

Operating systems allow applications to register handlers for new URL schemes. So, just as Firefox registers itself as the handler for official protocols like http://, the Last.FM radio application registers itself as a handler for lastfm://example/ URLs. Activating any URL prefixed with lastfm:// will then invoke the Last.FM application, rather than open it in a web browser. That behaviour applies to hyperlinks and redirects within web pages, IM conversations and email — it’s a system-wide way of linking between standalone applications.

To maintain the trust contexts of OAuth, your application needs to register a URL handler for your own custom protocol. It’s worth using a structured name, such as one derived from your product URL, to protect against collisions with other apps. e.g. x-net-yahoo-fireagle-iphoneapp://. Remember, it doesn’t have to be too comprehensible as it’s just for machine use, and you won’t be the only app wanting to use x-fireeagle://! (The x- prefix is a convention indicating that your protocol is a non-standard invention, rather than something official like gopher:// or http://.)

In OSX – both Mac OSX and iPhone OS — you can create custom URL schemes in the CFBundleURLTypes section of your application configuration plist, and then work with any input query arguments using a application:handleOpenURL: method.

  • In the iPhone SDK documentation, browse to ‘iPhone OS Programming Guide → The Application Environment → Application Configuration → Registering Custom URL Schemes’ — or just full-text search for ‘Application Configuration’ if you’re using the XCode documentation viewer.
  • For Mac OSX, equivalent documentation for registering and handling URL handlers is under ‘Cocoa Scripting Guide → How Cocoa Applications Handle Apple Events → Installing an Apple Event Handler → Installing a Get URL Handler’.

Twitterific developer Craig Hockenberry has released sample code showing how to use URL schemes for inter-application communication on iPhone OS.

On Microsoft Windows, protocol handlers are recorded in the Registry, under HKEY_CLASSES_ROOT.

Linux is fragmented into two separate desktop environments which have separate methods of registering URL handlers:

  • In KDE, create a .protocol file in $KDEDIR/share/services (likely /usr/share/services). Follow the instructions in How to register an internet protocol on the Kubuntu Forums to understand the precise file format.
  • In Gnome, you need to execute /usr/bin/gconftool-2 to add a URL handler, like so:
    1. $ gconftool-2 -s -t string /desktop/gnome/url-handlers/net-myapp-oauthcallback/command '/usr/local/bin/myapp "%s"'
    2. $ gconftool-2 -s -t bool /desktop/gnome/url-handlers/net-myapp-oauthcallback/enabled true

The Skype forums also contain instructions for configuring URL handlers in KDE, Gnome and Firefox: Making Skype links work.

If you have examples achieving this technique on other platforms, or fuller examples then we'd love to include them here. Please get in touch through the Fire Eagle mailing list group.

Pass the oauth_callback query parameter

When your application needs to authenticate with Fire Eagle, invoke the authentication URL in the user’s web browser. To elegantly switch from the standalone browser back to your application, include an oauth_callback URL parameter in your authentication request URL, using your newly registered custom protocol:

https://fireeagle.yahoo.net/oauth/authorize?
    oauth_nonce=1234
    &oauth_timestamp=123
    &oauth_consumer_key=abcd1234
    &oauth_signature_method=HMAC-SHA1
    &oauth_version=1.0
    &oauth_token=abcd1234
    &oauth_signature=asdfrhifFSDF2
    &oauth_callback=
      x-com-yahoo-fireagleapp://oauth-response/

After the user has logged in and granted permission to your application, the browser will redirect to the URL specified in oauth_callback (overriding any callback URL specified in your application configuration). When Fire Eagle redirects to x-com-yourcompany-fireeagle-iphoneapp://oauth-response/, the OS will invoke your application rather than take you to another web page.

On a platform such as iPhone OS2, where switching to the MobileSafari browser will cause your application to be closed rather than run in the background, the oauth_callback URL will start it again. For the user, they need never know the app was closed at all.


This documentation article is licensed under a Creative Commons Attribution License. We encourage reuse of this text as a base for OAuth documentation in your own applications.