Stake Ventures

FireEagle is Yahoo’s great new location web service which was recently launched into beta.

This review will not cover the API. A great little intro for this can be found in Interfacing a Rails App to Fire Eagle by Kamal.

I have previously written tutorial on writing OAuth Clients in Ruby or Turning your Rails site into an OAuth Provider. So I won’t go over any code here.

This is strictly about the user interface of FireEagle OAuth implementation. The FireEagle team Tom, Seth and Rabble have done an excellent job thinking about the UI and how it affects the security and privacy.

Which is great as most of the rest of us involved in OAuth have been worrying more about standards and implementations than usability. In reality Usability is one of those very important things that the security world tends to forget. So let’s learn from FireEagle’s example.

Registering your application

Firstly you need to make the sale to the application developers. FireEagle does this well. They let us know that FireEagle is nothing without the developer. More important they explain clearly the two main use cases for application developers.

We at Agree2 have a couple of interesting uses for this, so we’ll go ahead and register.

The registration is pretty clear. There are both security details and also information for including your application in their Application Gallery in the future

Of particular note are these settings which are one of the hints that the team have really thought about how OAuth integrates in their application.

Asking the developer what it is they need permission to do, allows FireEagle to ask the correct questions to the user later on.

Finally the application provides all the details to the developer of their consumer keys and secrets. Nothing particularly new here, however they do automatically create an AccessToken for the developer which is a pretty nice innovation that I also recently implemented (stole) into Agree2.

I am assuming that this AccessToken is basically the same as if I went and created an AccessToken manually. Anyone know if this has different rights?

Update Seth from the FireEagle team wrote me to say:

It does indeed have different rights. The access token provided on that page is a “general purpose access token”, which allows clients access to the ‘lookup’, ‘recent’, and ‘within’ methods (and not ‘user’ and ‘update’, as it doesn’t correspond to a user). Conceptually, this token is used for queries done “on behalf of the application” rather than “on behalf of the user”.

Anyway it’s pretty easy to plug this into your application using any number of libraries for just about any language out there.

End user Token Authorization

This is what happens when a Client Application asks a user to authorize them access to their data in FireEagle. A user would be redirected by the Client Application to this screen.

It is great the way it provides a very clear UI explaining the user without too much text exactly what it is they are giving them access to. FireEagle has a really neat way of describing various degrees of precision in sharing your location such as “exact location” or “my current neighborhood”. See below for the full list.

For a simple app like FireEagle it is possible to provide such a concise interface. We are still trying to figure out exactly what we should do in Agree2, as there are lots of potential ways this could be done.

Managing your tokens

Allowing users to manage their tokens is equally important. It provides a list of applications you have issued tokens to. As well as a plain English explanation of the permissions you have given them.

Editing your settings allows you to change permissions for the application.

Privacy in General

While this hasn’t got anything to do with OAuth in itself. Their general privacy settings are also very important. You can really see how the team has thought about Privacy here.

There is a prominent “Hide Me” button, which allows you to instantly “duck” out of site. Think of it like a mute button for FireEagle. This isn’t necessarily useful in all applications, but have a look at your own application if you can’t implement something like this. I assume technically speaking it disables all your AccessTokens until you enable them again.

It is also quick and easy to get rid of your location trail. For an application like FireEagle containing potentially delicate data, this is very important.

Another important aspect is that they automatically implement a timeout functionality. So if you forgot all about FireEagle it will automatically switch off your token’s access at an expiry date unless you specifically renew them.

All in all FireEagle is a great example of implementing OAuth completely into the Application but also on how to think of privacy in a way that I haven’t seen before in web applications.

We’re thinking how we can do just a good job in Agree2. Hopefully the FireEagle team aren’t to upset if we borrow and extend some of the new UI patterns they have come up with.

Create a simple NDA with zero legalese in no time at all and for free at our service Agree2.

On the request of many people here is a quick guide to developing OAuth Consumer Application (Consumer==Client in OAuth Speak) in Ruby.

I will be using Agree2 as the sample application here, so feel free to go Register and load up a irb session to follow along. You could also do the same with Twitter’s OAuth or any other OAuth server.

The general process is:

1. Register your consumer application with the OAuth compliant service to receive your Consumer Credentials (This is only done once)
2. You initiate the OAuth Token exchange process for a user by requesting a RequestToken from the Service
3. You store the RequestToken in your database or in the users session object
4. You redirect your user to the service providers authorize_url with the RequestToken’s key appended
5. Your user is asked by the service provider to authorize your RequestToken
6. Your user clicks yes and is redirected to your CallBack URL
7. Your callback action exchanges the RequestToken for an AccessToken
8. Now you can access your users data by performing http requests signed by your consumer credentials and the AccessToken.
9. ????
10. PROFIT!!!

Get your Consumer Credentials

Once you are logged in to Agree2 click the Manage OAuth Applications link in the footer:

All OAuth capable applications require you to register your own application first to get your consumer credentials:

Click Register your application

Enter the name of your application, the url of your application, the callback url and an optional support url.

The callback url is the url that Agree2 redirects to after a user has authorized a token for you. For now just enter a url like http://myapp.com/oauth_client/callback. Click register and hey presto:

These are your applications Consumer Credentials.

Hooking up your code

As we are nice guys here at Agree2 also provides actual sample Ruby code on the credentials screen. I will go through this step by step.

First of all you need to install the oauth gem (make sure you have at least 0.2.2):

sudo gem install oauth

Your code needs to require the gem and the consumer part of the library:

gem 'oauth'
require 'oauth/consumer'

Instantiate your Consumer object with your credentials:

@consumer=OAuth::Consumer.new "AVff2raXvhMUxFnif06g", 
                              "u0zg77R1bQqbzutAusJYmTxqeUpWVt7U2TjWlzbVZkA", 
                              {:site=>"https://agree2.com"}

Now request a token from Agree2. This method actually performs a signed http request to https://agree2.com/oauth/request_token :

@request_token=@consumer.get_request_token

Now you need to redirect the user to the authorize_url

If you’re in irb just output the url:

@request_token.authorize_url

In a real rails application you would perform a redirect:

redirect_to @request_token.authorize_url

The user will be taken to this screen to authorize the token:

I think we need to work a bit on the user interface for this. But it does work. The user authorizes the token. and the user is redirected to the callback url you specified earlier.

In your callback action you now need to exchange the request token for an AccessToken:

@access_token=@request_token.get_access_token

Now you are ready to do whatever you wanted to do:

# Request all your users agreements
@response=@access_token.get "/agreements.xml"

The access token object has all the normal http request methods and returns a standard ruby http response.

Our next step is to integrate this with ActiveResource. This is being worked on now. Once this is done I will update this tutorial.

Create a simple NDA with zero legalese in no time at all and for free at our service Agree2.

Today I released the new version of the OAuth Rails plugin . This finally supports the new “all together now” release of the OAuth Ruby Gem, which Blaine Cook and me have worked hard to merge together from our previous incarnations.

I previously posted a guide to how to turn your rails site into an OAuth Provider, which should still be pretty much be correct as there haven’t been too many changes to the api that you would use within your rails application.

See the OAuth Plugin Documentation for more detailed installation instructions.

If you are using the plugin or gem please join the OAuth-Ruby Google Group

Updating

If you have previously installed the plugin you need to first update your OAuth gem to the latest version. I’m afraid you also do need to rerun the generator. There haven’t been any changes to the view code so you can leave them be if you’ve made your own changes.

Credits

The new OAuth gem was basically a merge of my previous gem which we merged with the Blaine’s original OAuth code, which is used on Twitter. Large chunks of this has been written by Larry Halff and Jesse Clark of Ma.gnolia. Further help and patches came from amongst other people Pat Cappelaere, Jon Crosby, Seth Fitzsimmons and Phillip Pearson.

Create, negotiate and accept legally binding contracts for free with our Agree2 service.

I’ve made a few changes today to make it easier for other people to create OAuth Rails plugins using my core library.

The most important change is that I have pulled out most of the juice in the plugin into an OAuth GEM.

This means you now need to install the gem before you can use the plugin:

sudo gem install oauth

Easy.

I have also moved the plugin repository around a bit. I’m sorry if you’ve alredy installed it. I made a mistake when I first created it. Now it should have a better url for installing as a plugin:

script/plugin install http://oauth-plugin.googlecode.com/svn/trunk/oauth_plugin

I have updated the instructions in my last post How to turn your rails site into an OAuth Provider

Last but not least I started an oauth-ruby mailing list for Ruby specific implementation issues. Rails developers tend not to be scared of trying new things and it would be better to leave questions about integrating them with specific authentication libraries etc to a separate list.

If you are interested in the actual standard you should also join the main OAuth list.

Phew. off to bed. If you have questions and you’re at the SF Ruby meetup today come up and say hi.

Create, negotiate and accept legally binding contracts for free with our Agree2 service.

This has been updated on the Nov 27th 2007. Please read below if you have already installed it

OAuth is the great new standard allowing your users to use your application to talk to their accounts on other applications. I won’t go more into it here as it’s pretty well covered on the OAuth site.

I have created an OAuth Rails Plugin and an oauth gem which will help you to create both oauth providers and consumers.

Consumers and Providers

I will cover consumers in another post, but it’s probably a good idea to explain what the difference is:

A consumer is an application that uses another web applications data. For example for a mashup. It is mainly intended for web applications, but there is nothing to stop you from writing say a way cool Mac client in Cocoa as well.

A provider is a web application that the consumer wants to access.

The classic example is a photo printing site as a consumer and a photo site (like Flickr) as the provider.

Provider features

The plugin can generate an oauth provider that supports the following out of the box:

• User can register their own applications to receive consumer key/secret pairs.
• Provider supports standard best practises out of the box hmac-sha1 etc.
• Users can manage and revoke tokens issued in their name
• Easy before filter to provide oauth protection on your actions

sudo gem install oauth

script/plugin install http://oauth-plugin.googlecode.com/svn/trunk/oauth_plugin

script/generate oauth_provider

map.oauth '/oauth',:controller=>'oauth',:action=>'index'
map.authorize '/oauth/authorize',:controller=>'oauth',:action=>'authorize'
map.request_token '/oauth/request_token',:controller=>'oauth',:action=>'request_token'
map.access_token '/oauth/access_token',:controller=>'oauth',:action=>'access_token'
map.test_request '/oauth/test_request',:controller=>'oauth',:action=>'test_request'

has_many :client_applications
has_many :tokens, :class_name=>"OauthToken",:order=>"authorized_at desc",:include=>[:client_application]

rake db:migrate
script/server

before_filter :login_or_oauth_required

before_filter :login_required,:except=>[:show,:index]
before_filter :login_or_oauth_required,:only=>[:show,:index]

before_filter :oauth_required

Create a simple NDA with zero legalese in no time at all and for free at our service Agree2.