A growing number of websites are adopting OAuth to authorize third-party applications to interact with a user's resources. For example, back on August 31, 2010, Twitter flipped the kill-switch on Basic Auth and starting requiring all third-party Twitter applications to authenticate using OAuth. Other sites (ie: service providers) supporting OAuth include Evernote, Google, LinkedIn, MySpace, Photobucket, Vimeo, Yahoo, among many others.
OpenSocial defines a specification that allows gadgets to leverage OAuth to access protected resources from service providers which Liferay's OpenSocial portlet has now implemented. In this blog post, I will demonstrate how to configure OAuth for an OpenSocial gadget in Liferay. This example will showcase a simple Twitter gadget that shows the authenticated user's tweet timeline and allows status updates.
Note: The code to support OAuth for OpenSocial gadgets is implemented in portal trunk (revision 71759). You can grab and build the latest source code from Liferay's repository to use this feature. Otherwise, you will need to wait for the 6.1 release of the portal.
Before we begin configuring our OAuth gadget, let's first take a brief look at the gadget's XML structure. You can find the full XML for the gadget here: link.
Within the ModulePrefs element, we see the following OAuth element:
<OAuth> <Service name="twitter"> <Request url="http://api.twitter.com/oauth/request_token" param_location="uri-query" /> <Access url="http://api.twitter.com/oauth/access_token" param_location="uri-query" /> <Authorization url="http://api.twitter.com/oauth/authorize" /> </Service> </OAuth>
Gadgets using OAuth should define a Service Name and its Request, Access, and Authorization URL. These URL's are provided by the service provider (Twitter in this example: link). See the OpenSocial wiki for more information on these parameters: link.
Note that gadgets.io.makeRequest() is part of the 0.7/0.8 OpenSocial spec and has since been deprecated. The 0.9+ spec defines a simpler, more intuitive methods in osapi.http.get/post, however it seems Twitter doesn't return the expected results when the user has not yet granted access to the gadget. As a result, I used the deprecated methods in my Twitter gadget. I've contacted Twitter about osapi.http support and hope to hear back soon. More information on gadgets.io.makeRequest and osapi.http can be found here: link.
Now let's configure our gadget. We need to define the consumer key and secret given by our service provider.
- Open the OpenSocial configuration page in the Control Panel. First add the gadget via URL as you would with any other gadget. (https://raw.github.com/dejuknow/opensocial-gadgets/master/Twitter/Twitter.xml).
- For any OAuth enabled gadgets, you'll see a "Manage OAuth" pop-up option under "Actions". Click on "Managed OAuth".
- You will see a list of all the service names defined in your XML. To use a service, we will need to enter a consumer key and secret. In our case, we have one service named "twitter". Click on the link.
- Now we need to retrieve a consumer key and secret from our service provider (Twitter). Go to http://dev.twitter.com/apps (sign in if you haven't already) and click on "Register a new application".
- Fill out all necessary information.
- For the "Callback URL", enter Liferay's default callback URL: "http://myLiferayServer/opensocial-portlet/gadgets/oauthcallback". (replace myLiferayServer with an appropriate value. 127.0.0.1:8080 will work for demonstration sake).
- For "Default Access Type", select "Read & Write" as we will need to write access to post status updates.
- After registering, Twitter will provide you with a consumer key and secret as well as the request token URL, access token URL, and authorize URL. Take note of the consumer key and secret. Also note that Twitter uses the HMAC-SHA1 algorithm.
- Enter the "Consumer Key" and "Consumer Secret" in the OpenSocial Control Panel page. Select "HMAC_SYMMETRIC" for the "Key Type" then click "Save".
Adding the Gadget
- Now we're ready to add the gadget to a page. Go to "My Private Pages" and click on "Add" -> "More" -> "OpenSocial" and add "Twitter Gadget".
- Click on "Personalize this gadget" to be redirected to the service provider.
- Twitter will ask the end user whether your application (ie: your gadget) should be given "the ability to access and update your data on Twitter". You can sign out and sign in with another Twitter account here. Click "Allow".
- The pop-up window should close and your gadget should now show the last 20 tweets from your timeline.
- You can use the gadget to tweet your new status update. (Note: you can also change the number of tweets to display by clicking on the wrench icon on the upper right and going to "Configuration". The screenshot below shows the last 5 tweets instead of the default 20.)
That's it! I hope this blog entry helps you get started creating OpenSocial gadgets that require OAuth. Feel free to leave a comment below if you have any questions.