Developing gadgets with Ruby: gadgeteer

When developing an OpenSocial gadget, we may need to communicate with a background application from our api. The platform provides great methods for this, making the whole process feel like developing a well-supported AJAX-intensive web application. Due to the flexibility of the platform and quick development, a Ruby framework is excellent for the back-end. In the following I am going to present a couple of appliances which are useful in back-end development. Among others, we open the source of a Rails plugin developed by Virgo, which simplifies a couple of things.

Back-end access

Communication with the back-end is enabled by means of the gadgets.io.makeRequest function. This works basically as an average proxied cross-domain ajax request, either signed or unsigned. We should not expect much on the server side in the case of unsigned requests, it is almost identical with an average ajax request. Please note that session handling will need some attention in order to work. As a result, Rails’ built-in CSRF protection will be disabled, but – as we shall see – it is no problem, as signed request provide sufficient protection.
There are two ways of signed polling. One is using signed requests. In this case the OpenSocial container generates a cheksum from the request parameters using a private key or a shared secret. From this, the remote server will know that the request is really from the expected location. The application ID and the IDs of the viewer and the owner user are among the signed parameters. The request cannot be faked without the key, so we can be sure that the request had been sent by the OpenSocial container and the submitted data are authentic. From this it is evident that there is sufficient CSRF protection, therefore it is recommended to use signed requests for all but GET requests.
The other way is using oauth, where the signature works the same way, but the request process is more complex, because it includes an additional authentication step. It comes in handy when we need to connect an OpenSocial profile with one of our users on the back-end, requiring authentication. This topic shall be discussed in detail later, in an upcoming post.

Checking signed requests

Signed requests have been discussed on the iWiW developer blog, it may be worth a checkback on client end details. A ruby problem, one popping up when checking signed requests, cropped up among the comments to the developer blog.
To check signed requests in Ruby one needs the oauth gem. The current version of the gem contains a bug, which causes the request parameters to be escaped too much in the checksum generation process, resulting in a faulty check code. There is no official patch for it yet, but there are a number of solutions for the problem in the GitHub forks. The patch is available for the version of the gem I have forked. This version also includes a Rails Edge compatible fix.I recommend to have the gem installed from here, until the official fix arrives with the new version. (A pull request has been sent and apparently the developer list is waking up, so there is hope.)

Some help for installing from github:

$ git clone git://github.com/lackac/oauth.git
$ cd oauth
$ rake gem
$ sudo gem install pkg/oauth-0.2.7.gem

Introducing gadgeteer

To facilitate the checking process and gadget backend development we have prepared a Rails plugin in-house to unburden developers as much as possible. The plugin is called gadgeteer and it is available on GitHub under the MIT licence.

Installation:

$ script/plugin install git://github.com/virgo/gadgeteer.git

Currently, the plugin helps in three areas. It makes keys easy to configure, OpenSocial-specific parameters from the container easy to access and simplifies checking of inbound requests.

Keys

There are two methods for storing keys. Either under the config library or configured in one of the containers (Application Controller is obvious).

In case of public keys files with the .cert extension shall be stored in the config/cert library or entered in the public_keys hash of the controller as an instance of the OpenSSL::PKey::RSA class respectively. Gadgeteer selects the corresponding key according to the xoauth_signature_publickey request parameter (whose value is ‘iwiw.hu’ in the case of iWiW).

Checking

We can perform checking inbound requests by using the verify_signature method. This can be set directly in a before_filter. The implementation takes care of selecting the proper key and checks the signature using the proper method.

Access of OpenSocial parameters

In case of signed requests we get a couple of useful parameters. The container adds the ‘opensocial’ prefix to them. They can be accessed with the param method, but the gadgeteer plugin has a more evident meethod called open_social. This way the viewer gets the ID open_social[:viewer_id], the application open_social[:app_id]. Furthermore, the parameters beginning with ‘os_’ are also included, so that further OpenSocial-specific parameters could be pooled here by the client end. (For example, further data requested about the viewer from the client end can then be forwarded to the back-end in ‘os_viewer_*’ parameters.)

The example codes included in the project’s README illustrate the above even more.

Plans for the future

We intend to extend the plugin with further useful aspects coming up during api development. We are also open for new recommendations, but we cannot promise to implement every idea. On the other hand, we are more than interested in pull requests sent through the GitHub about your enhancements to the plugin.