OpenSocial, OAuth and Nuxeo EP

About Opensocial

OpenSocial is a community standard managed by the OpenSocial foundation. Several major companies (Google, IBM, SAP, Atlassian ...) are involved in the OpenSocial standard.
You can consult the full OpenSocial specification here, but at a glance OpenSocial scope includes :

JavaScript/Html gadgets

OpenSocial gadgets are small HTML/JavaScript applications that consume data using REST WebServices.

The idea is similar to the JSR 168 portlet with some differences :

• rendering is mainly done on the client side (Browser side)
• OpenSocial gadgets are independant of the server side technology (Java, Php, Python, .Net ...)
• deploying a new gadget is simply referencing a URL that contains the XML gadget spec

Gadgets are run in a Container that is responsible for providing the gadget with the rendering environment and needed JavaScript APIs.

Rest WebServices

OpenSocial defines a set of Rest WebServices that must be implemented by compliant container.

The main services are:

• App Data service  : service to store user specfic data for each gadget / app
• Groups service : manage relationship between users. (each user has the ability to manage his own groups : friends, coworkers, ...)
• Activity service : track user activity
• Person service : standard access to the users of the system
• Message service : simple messaging system

These web services provide the "social part" of the OpenSocial technology.

Manage authentication and security of data accesses

In OpenSocial there are usually 3 actors:

• the user : the human looking at the gadget inside his browser
• the container : the "server" providing the container page where the gadgets are rendered
• the service provider : the server providing the Rest service accessed by the Gadget

Additionally, the AppId (i.e. the gadget) may be taken into account.

Also, OpenSocial differentiate 2 types of user identify:

• the viewer : the user in front of the browser
• the owner : the user owning the page that contains the gadget

If you take the example of a gadget that display inside Nuxeo your emails from GMail :

• you are the user (OpenSocial viewer and OpenSocial owner)
• Nuxeo is the container
• GMail is the service provider
• the GMail gadget is the AppId

Because Gadgets are HTML/Javascript, the gadget can not call directly GMail (Cross site scripting issue), so the container will proxy all calls from to gadget to GMail.

So, the container (here Nuxeo) will manage REST call proxying :

• handling caching if needed
• handling security

The security part is not trivial because in OpenSocial contexte there are 3 constraints :

• you need to delegate authentication to a server
  (i.e. let Nuxeo connect to GMail on behalf of me)
• your GMail and Nuxeo account may be completely unrelated
  (not the same login for example)
• you may not want to let Nuxeo access all your GMail data, but only a subset

In order to manage theses requirements OpenSocial relies on OAuth.

Nuxeo EP server can be used both as an OAuth Service consumer or as an OAuth Service provider.

You can find more details about OAuth and it's integration in Nuxeo later in this page.

What can it be used for

Dashboard / Portal use case

The most direct use cases is to use OpenSocial gadgets to adress Dashboard / Portal use case.

This is currently the default usage of OpenSocial within Nuxeo CAP / DM.

For that, we have created some simple and extensible gadgets :

• My recent documents
• My Workspaces
• My Tasks
• ...

The user can then use the Nuxeo's dashboard to have a quick overview of it's activity inside Nuxeo platform.

Using OpenSocial gadgets to do so is interesting because :

Let users control their Dashboards.

Depending on the security policy, the user is able to customize it's dashboard

• add / remove gadgets
• change gadgets configurations

Leverage an open standard

Gadgets can come from several différent services providers

• My Tasks on Nuxeo
• My Task on Jira
• My Google calendar events

More and more application are supporting OpenSocial:

• Google Apps
  (also provides an OpenSocial container in GMail and iGoogle)
• Atlassian Jira and Confluence
  (that are also OpenSocial container)
• SAP
• SalesForce.com
• Social Oriented services like LinkedIn, MySpace, Hi5, Orkut ...
• ...

So you can add external gadgets to Nuxeo's Dashboard, but you can also use an external OpenSocial Dashboard provided by an other application and use Nuxeo's gadgets from inside this container.

Manage user identity

Because OpenSocial relies on OAuth you can have a narrow controle of what service may be used and what scope of data you accept to share between the applications.

Simple deployment

Deploying an OpenSocial gadget in a container is as simple as giving a new Url.

Easy contextual information integration

OpenSocial gadgets can also be used to provide a simple and light integration solution between 2 applications.

For exaample, you can :

• display some informations comming from SAP next to the Invoice Document in Nuxeo
• diplay links to related Nuxeo Documents from within a confluence wiki page
• display specification documents (Stored in Nuxeo) from withing the Jira Issue

An more generally, if you have Enterprise wide Rest WebService (like Contacts managements, Calendar management ...) you can expose them via OpenSocial gadgets so that theses services are accessible to users of all OpenSocial aware applications.

Social network management

Because OpenSocial standardize a set of Social oriented services, you can easily leverage the data from all OpenSocial aware applications.
For example you can have an aggregated view on the activity stream.

In the context of Document Management, Collaboration and KM, Social APIs really makes sense :

• manage communities
• manage activity
• manage user skils
• ...

OAuth in Nuxeo EP

Starting with 5.4.1, Nuxeo EP provides full support for OAuth.

Nuxeo as a service provider

You may want to use Nuxeo as an OAuth Service provider :

• if you have an OpenSocial gadget that uses a REST service from Nuxeo
• if you have a external application that uses a REST service from Nuxeo

Unless the service consumer is a gadget directly hosted inside Nuxeo, you will need to do some configuration at Nuxeo's level to define how you want the external consumer to have access to Nuxeo.

Nuxeo as a service consumer

If you need to access an external REST service from within Nuxeo, you may want to use OAuth to manage the authentication.

If you use this external service from within an OpenSocial gadget, you will need to use OAuth.

Unless the service you want to consumer is hosted by your Nuxeo instance, you will need to do some configuration do define how Nuxeo must access this external service.

For more details about OAuth support in Nuxeo, please see the dedicated section.

Nuxeo Automation REST services

OpenSocial gadgets typically use REST services to fetch the data from the service provider.

When Nuxeo is the service provider, the recommended target API is Nuxeo Automation :

• provide a solution to easily have custom REST Apis without having to write code
  (Using Nuxeo Studio)
• common access point for all REST services
  (All Operation and Chains can be called the same way)
• native support for JSON marshaling 
  (means easy integration in the Gadget JS)
• built-in samples in Nuxeo Gadget
  (see below)

If you have already built custom automation chains to expose a high level API on top of Nuxeo, you can easily expose theses services via an OpenSocial gadget.

Gadgets in Nuxeo EP

Apache Shindig, GWT and WebEngine

OpenSocial integration in Nuxeo is based on Apache Shindig project.

Nuxeo OpenSocial modules were originally contributed by Leroy Merlin and includes :

• Shindig integration
• a WebEngine based Gadget spec webapp ( /nuxeo/site/gadgets/ )
• a GWT based gadget container
• a service to contribute new gadgets

Gadget spec generation

Gadget Spec is the XML file defining the Gadget.

It's a static XML file that :

• describes the gadget
• list the required features of the gadget
• contains the translation resources
• contains the authentication informations
• contains the Javascript files and HTML content
• ...

Inside Nuxeo, the Gadget Spec is dynamically generated from a FreeMarker template using WebEngine.

Using WebEngine and Freemarker to generate the spec add more flexibility and power :

Better reusability 

Most of you gadgets will share some common content.

For Javascripts it's easy to manage, but for HTML and XML content it not that simple.

In order to avoid that issue, when writing a gadget spec in Nuxeo, you can use Freemarker includes that will be resolved :

• locally to the gadget directory
• globally in the webengine-gadget bundle (in skin/resources/ftl)

The same logic applies for JS et CSS resources that will be resolved :

• locally to the gadget directory
• in the gadget bundle
• globally in the webengine-gaget bundle (in skin/resources/scripts or skin/resources/css)

Better context management

When generating the GadgetSpec you need to take into account several parameters :

• urls : resources URLs may be dependent of your config
  • Nuxeo host name may change
  • some resources are accessed from the client side (from the browser)
  • some resources are accessed from the server side (Server to Server communication)
• Authentication : depending on the target Host of the gadget authentication config may change
  • you want to use 2 Legged integrated authentication when gadget is inside Nuxeo
  • you want to use 3 Legged authentication when gadget is hosted inside an external application 

In order to address these problem the Freemarker template is rendered against the fellowing context :

The inside flag is "automatically" determined by Nuxeo, but in case the consumer application and Nuxeo are on the same host (i.e. communication via locahost or 127.0.0.1), you may force the external mode by adding external=true to the gadget spec url :

All request parameters you may pass in the gadgetSpec url will also be available at the root of the freemarker context.

Integrated internationalization

GadgetSpec needs to provide XML files for all translations.

So, of course you can use static resources for these translation files.

The main problem is that in this case you can not leverage the existing translations in Nuxeo and it's hard to contribute new translations.

In order to avoid that, Nuxeo proposes a dynamic translation mode, where messages files are dynamically generated based on the standard messages files used in the JSF webapp.

To activate the dynamic i18n features you need :

• to provide a dynamic_messages.properties file that will list the needed label codes and associated default values
• use the include that will automatically generate the needed translation files and associated entries in the XML Spec

Dynamic management of Authentication

As explained earlier, depending of the target context, the Spec needs to define OAuth 3 legged or 2 Legged.
You can do it by hand, or you can use the oauth include :

Gadget Toolbox

In order to make Gadget creation easier, Nuxeo provides some building blocks for common features :

• Context management
• Automation REST calls
• Documents list display

These building blocks are composed of Freemarker includes, JavaScripts files and CSS files.
Thanks to these building blocks, writing a full featured gadgets base on Automation API is very simple.