OAuth in OGCE gadget container

OGCE gadget container makes support of OAuth as easy as possible.

Follow two files are the most important related to OAuth configuration.

1. config/shindig/shindig.properties
   Most important config parameter is shindig.signing.global-callback-url. It has been rewritten correctly so the end users don’t need to worry about it.
2. config/shindig/oauth.json
   This files contains information of all consumers of which the OGCE gadget container is a proxy.

If you want to write OAuth gadget, follow instructions showed on this page: http://code.google.com/apis/gadgets/docs/oauth.html.
More complicated cases: http://sites.google.com/site/oauthgoog/oauth-proxy/social-oauthproxy

Resources about OAuth support in Gadget

http://sites.google.com/site/oauthgoog/oauth-proxy

http://code.google.com/apis/gadgets/docs/oauth.html

http://code.google.com/apis/accounts/docs/OAuth.html

http://groups.google.com/group/oauth/browse_thread/thread/5dea93b44dbbb628

OAuth test client: http://term.ie/oauth/example/client.php

Google OAuth Playground: http://googlecodesamples.com/oauth_playground/ (just for Google’s APIs)

2-legged OAuth System Tutorial

Use Cases:

(1) A user wants to grant data access priviledges to a third-party application.
  Here three parties are involved:
  User
    the end user
  Third-Party application
    It wants to manipulate user's data on behalf of the user.
  Service Provider
    a remote application that provides the real service.

  The procedure of granting priviledges:
  (I) complete steps described in section
      (Provider side) > (For regular users)
  (II) complete steps described in section
      (Consumer side) > (For regular users)
  Note: the public key uploaded in step (I) and private key uploaded in
  step (II) must match.

(2) A user wants to develop a third-party application for our service.
  (I) Register the application by completing steps described in section
      (Provider side) > (For thrid-party application developers)
  Now, the application can use the service.

  (II) To make use of built-in third-party application, complete steps
    described in section
      (Consumer side) > (For application manager)

(3) A user wants to use a deployed and configured third-party application.
  (I) Go to http://yourhost:yourport/oauthConsumer-0.1
  (II) Login with existing account and you will be directed to page 'account.jsp'
  (III) All supported third-party applications are listed under section
  (Available service providers). Click a link to use the corresponding
  application.

 

Consumer side

For regular users

Steps
  (1) Go to http://yourhost:yourport/oauthConsumer-0.1
  (2) Register a new account or log in with existing account
  (3) Go to account.jsp (you should be automatically directed to this page)
  (4) If it is the first time for the user to request an OAuth protected
      service via client application, the user should do some configurations.
      Click the link "Private Key Binding And Service Provider Setting"
  (5) On this page, user can do some configurations
    (5.1) UserId binding
      This setting binds local user Id to user Id used by remote service.
      For example, if a user wants to access remote Yahoo flickr service
      through a third-party app, the local user Id is the user id used by the
      third-party app and it is bound to the user Id used by Yahoo Flickr.
    (5.2) Private key setting
      Possession of private key makes the third-party app be able to access
      remote service on behalf of the user.

For application manager

Actually, only administrators should have the priviledge to manage third-party
application registry. But currently user management system is simple and all
users have the same priviledges.
Steps
  (1) Go to http://yourhost:yourport/oauthConsumer-0.1
  (2) Register a new account or log in with existing account
  (3) Go to account.jsp (you should be automatically directed to this page)
  (4) Click the link "Attributes of available service providers"
  (5) Now, the user can register a new third-party app, remove an existing
      registration and modify existing registration information.

Provider side

Currently, only one service is offered - echo service.

For regular users

Steps
  (1) Go to http://yourhost:yourport/oauthServer-0.1
  (2) Register a new account or log in with existing account
  (3) Go to account.jsp (you should be automatically directed to this page)
  (4) Click the link "Certificate Setting"
  (5) On this page, user can do some configurations
    (5.1) Third-party app priviledge setting
      Users can specify which third-party applications are allowed to access
      their data.
    (5.2) Certificate upload
      Upload your X.509 certificate (of PEM format).

For thrid-party application developers

Steps
  (1) Go to http://yourhost:yourport/oauthServer-0.1
  (2) Register a new account or log in with existing account
  (3) Go to account.jsp (you should be automatically directed to this page)
  (4) Click the link "Developer Account"
  (5) Type information of the third-party application that is to be registered.
      A consumer key/secret pair is generated as well.

Use of Public/Private key pair

There are two types of private/public key pair:
(1)
    One is used to guarantee integrity of messages transmissioned between
  third-party application and service provider.
    So for service provider, the public key is published. If a third-party
  application wants to access the service, it should use the published public
  key to sign outbound messages.
(2)
    The other is owned and deployed by end user. The goal is to provide a way so
  that third-party application can use backend service on behalf of user
  without user involvement.
    So this pair is owned by end user. To deploy the key pair:
  (*) upload the public key to service provider
  (*) upload the private key to third-party application
    Then the third-party application uses the private key to sign part of the
  message (The whole message is signed using pub/priv key pair described in
  bullet 1).

OAuth message

    ___________________________________________________________
   |                                                           |
   |     _________________________________________________     |
   |    |   ___________________________________________   |    |
   |    |  |  ______________       _________________   |  |    |
   |   P|  | |              |     |                 |  |  |    |
   |   a|  | | Payload 2    |     |  Signature (2)  |  |  |    |
   |   y|  | |______________|     |_________________|  |  |    |
   |   l|  |___________________________________________|  |    |
   |   o|                                                 |    |
   |   a|   ___________________________________________   |    |
   |   d|  |                                           |  |    |
   |    |  |                Other parts                |  |    |
   |   1|  |___________________________________________|  |    |
   |    |_________________________________________________|    |
   |     _________________________________________________     |
   |    |                                                 |    |   
   |    |       Signature (1)                             |    |
   |    |_________________________________________________|    |
   |                                                           |
   |___________________________________________________________|

In above figure, <Signature (1)> is calculated using key described in bullet 1. <Signature (2)> is calculated using key described in bullet 2.

Implementation of 2-Legged OAuth

2-Legged OAuth

I did not change the process flow of original 3-legged OAuth to support 2-legged OAuth. I made a small change to user authorization step described at http://oauth.net/core/1.0/#auth_step2. Two additional parameters are added to support 2-legged OAuth: user_id and cgl_oauth_signagure. See http://zhenhua-guo.blogspot.com/2009/04/oauth-myproxy-integration-prototype.html for more information.

Integrity check:

1. check trust relationship between service provider and client app.
   Currently, just check whether the clien app has been registered at service provider with correct information.
2. check pre-assigned priviledges to client app by user (this only applies to 2-legged OAuth)
   A client app must have been granted access priviledge before it can access user data stored at service provider
   

Implementation

Client

Client App

Most important information about a client application includes:

• name
• description
• consumer key
  See http://oauth.net/core/1.0/#anchor6
• consumer secret
  See http://oauth.net/core/1.0/#anchor6
• callback URL
  The address to which user is redirected after data owner accepts access request.
• signature method
  HMAC-SHA1 or RSA-SHA1. Currently, only use RSA-SHA1.
• private key
  Used to generate signature
• request token URL
  See http://oauth.net/core/1.0/#auth_step1
• authorization URL
  See http://oauth.net/core/1.0/#auth_step2
• access token url
  See http://oauth.net/core/1.0/#auth_step3

A list of client applications is listed and users can add or remove client applications.
Snapshot:

Users can set userid that is used during invocation of remote service. Also to make it possible for client app to access user data at service provider, the user should upload private key to client app so that correct signature can be generated during OAuth process.

Tables

Four tables in database:

oauth_consumer_users

This table stores basic user account information. Currently, username and password are the only two attributes.

oauth_consumer_settting

This table stores private key belonging to each user. The private key is used during OAuth authorization process.

oauth_consumer_spbinding

This table stores binding relationships between users and service providers. So the information in this table is used when client app invokes remote service on behalf of user. Currently the main information is the user id that is used by service provider. In other words, a mapping from local user id to remote user id is established.

oauth_consumers

This table stores information of client applications.

Service Provider

Service provider provides interfaces that can be used by third party applications to access users' data.

For application developer

Client application registration

To register a client app, developers need to follow these instructions:

1. apply for a consumer key/secret pair.
2. type informatoin about the clien app including
   • app name
   • app description
   • app callback URL
   • public key

In my implementation, the registration page can be accessed at <baseurl>/oauthServer-0.1/developerAcc.jsp after our system is installed.
Screenshot:

For common users

Some third-party applications may want to access users' data stored at service provider. In 3-legged OAuth, the service provider redirects the user to a web page where the access request can be accepted or denied. In 2-legged, no user intervenetion is involved, so the authorization setting must be preset.
In our system, we provide a way for common users to grant priviledge to and revoke priviledge from client (3rd party) applications. Also the user must upload a public key against which signature of requests receieved from client app can be verified.
Snapshot

Tables

oauth_server_users

Basic user account information. Currently, just includes user name and password.

oauth_server_setting

stores public key extracted from myproxy server or direct upload.

oauth_server_dev

Stores information of registered client applications.

oauth_server_userappauth

Stores information of priviledge authorization set by each user.

OAuth + MyProxy integration prototype

Client

Client is the consumer of backend services.
Functionalities

• A simple user management system
  Users can create new accounts, log in the system and log out the system.
• Each user can upload her/his private key
• For each backend service, the user can set his/her user id which is bound to the backend service.
  
  In above figure, the end user logins the client app as user "john". The client support accessing of three backend services. Then the user sets the binding of user id to each backend service. When the user wants to invoke backend service 1, the client app would set the user id to "mark" in the requests.

Service Provider

Functionalities of the service provider:

• A simple user management system
• Each user can bind a MyProxy account to his/her local account.
  The needed information of MyProxy account includes username, password, MyProxy server host and port number.
  Then the server would automatically retrieve a certificate chain from the specified MyProxy server. After parsing the certificate chain, public key of the original certificate that belongs to the user is extracted.
  Note: we don't use public key included the proxy certificate. There is just one original certificate stored in the MyProxy server while many proxy certificates can be acquired. Each time a new proxy certificate is requested, a new public/private key is created and the public key is sent to MyProxy server. Usually, this process is done by system automatically.
• Each service could be accessed by various client applications. Users can set which client apps are allowed to access their data.

OAuth Integration

In OAuth authorization procedure, there are three main steps:

1. Get a request token
2. Ask user to authorize the request
3. Exchange request token with an access token

Then the access token acquired in step (3) is used to access protected resources.
Trust relationship between client app and service provider is built out of band. Two mechanisms are supported: shared secret and RSA.
In my solution, step (2) is extended with step (1) and (3) staying the same. Two additional parameters are added: user_id and cgl_oauth_signagure. Parameter user_id is described here. The cgl_oauth_signature is calculated against user_id using the user's private key. After service provider receives the request, the corresponding public key (retrieved from MyProxy server) is used to verify the signature.

Future Work

1. Revoke the authorized privileges
   1. Users can set an expiration time after which the access token will become invalid. Then the whole OAuth authorization process must be executed once again.
   2. Provides a way for user to revoke authorized privileges at any time they like.
2. Trust relationship establishment.
   Developers of client apps go to specified web page of the service provider to apply for development account. Then one of the following two things happens:
   • A shared secret would be generated automatically and copied to the corresponding client app.
   • The developers of the client apps upload their certificate to backend service.

Deploy standalone shindig on Quarry and an OAuth gadget demo

I got a virtual machine which I can log in as root. The virtual machine is pretty clean without any more packages besides CentOS.
I installed vim using yum install vim-enhanced. I also installed jdk1.5 and maven2.

Then I checked out the source code from shindig svn trunk. See instructions here http://incubator.apache.org/shindig/#tab-building.
Unfortunately, the test failed when I compiled and installed shindig. This kind of things always happens because of instability of trunk code. So I copied my previous checkout of shindig code which worked well from another machine. Then the compilation and installation succeeded.

OAuth gadget demo to retrieve google contact list

Now the sample demo is here:
http://gw11.quarry.iu.teragrid.org:9999/gadgets/files/samplecontainer/samplecontainer.html

Set field "Displaying gadget" to http://156.56.104.196:8888/oauth/gadgets/os_gadget.xml, Uncheck "use cache".
Click button "reset all". If everything works fine, you would see following in main panel:

Clieck "Personalize this gadget", a popup window would appear which prompts you to login to your google account. Then you can choose grant or deny the access request. If you grant the request, the popup window would be closed automatically, and the main panel would be populated with your google contact list.

Integration of OpenSocial containers via OAuth

For OpenSocial gadgets,  OpenSocial containers are necessary to hold users' data (friends, profile, ...). In Javascript API, class opensocial.DataRequest can be used to get users' data from the container which renders the gadget.

But to integrate users' data from third-party OpenSocial containers, some additional steps are needed. opensocial.DataRequest does not allow gadget developers to specify which OpenSocial container would be used to serve the data. Also the gadgets can not send requests directly to third-party containers because of Same-Origin policy imposed by browsers.

Method gadgets.io.makeRequest can be used to send arbitrary HTTP GET/POST requests. These requests are sent to the original container first. The original container does some processing and relays the requests to the destination address.
http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.io.makeRequest
http://code.google.com/apis/opensocial/articles/makerequest-0.8.html
http://code.google.com/apis/gadgets/docs/remote-content.html

Both REST and RPC protocol specifications requires that compliant containers must be OAuth service provider:
http://www.opensocial.org/Technical-Resources/opensocial-spec-v081/restful-protocol (Section 4)
http://www.opensocial.org/Technical-Resources/opensocial-spec-v081/rpc-protocol
Also I found OAuth Consumer Request 1.0 Draft 1 (hosted at googlecode, not oauth.net) which standardizes two-legged authorization process without a User involvement. It is useful in server-to-server interaction.

How to use OAuth in gadgets
http://code.google.com/apis/gadgets/docs/oauth.html (Very useful)
http://sites.google.com/site/oauthgoog/oauth-proxy/social-oauthproxy

OpenSocial container list:
http://wiki.opensocial.org/index.php?title=Main_Page#Container_Information

Extensions:
Also, I found many OAuth extension drafts which are not listed in OAuth.net. I guess these extensions are implemented in Shindig and evaluated.
http://oauth.googlecode.com/svn/spec/ext/

Web2.0 Integration Summary

The server-side architecture is described here:
http://zhenhua-guo.blogspot.com/2008/05/mashup-architecture.html.

Authentication: OpenID which is described here (http://zhenhua-guo.blogspot.com/2008/05/openid.html).
Authorization: Although OAuth seems promising, it has not been supported by large web 2.0 applications. So, I make use of various authorization mechanisms of different applications.

RESTful web services are used instead of SOAP-based web services. URL pattern used to access various resources is described here(http://zhenhua-guo.blogspot.com/2008/05/url-pattern-in-mashup.html).

At client side, Ajax is used to enhance user experience. Client side functionality is described here(http://zhenhua-guo.blogspot.com/2008/06/client-side-techniques.html).

OAuth

In my mashup framework, OpenID is used to do authentication which provides a way to make sure the users are really who they claim to be. The mechanism is that the users prove that they own/control the OpenID they provides. Here is what I wrote about OpenID.

However, OpenID just solves authentication. After users are authenticated, OpenID does not specify how the third-party apps access the protected data on service providers. And the requirement that third-party apps can access protected data stored on service providers on behalf of users is not imaginary, but real. In my mashup framework, I need to manipulate data on behalf of users which needs authorization besides authentication. Youtube and Flickr both provide ways for third-party integration. They provide similar authorization procedures (I am using this mechanism right now) which fundamentally match principles of OAuth specification.

OAuth provides a way for users to grant access to third-party apps. The procedure is pretty much the same as OpenID. What is different are parameters in requests and responses. OAuth is an independent specification which means it is not an extension of OpenID. But, in my opinion, it may be better to combine these two together because they are similar to each other. In this way, user experience can be improved because authentication and authorization can be done in the same pass instead of two. However, some sites may just support authentication service or authorization service (in terms of support of open standards like OpenID, OAuth). So how to combine them together without losing flexibility is an issue.

One problem that OAuth does not address is fine-grained access control. I think this issue must be addressed in the long run. However, nowadays, the goal is too far to reach. Actually, current version of OAuth is not supported widely.

DataPortability is a new organization which aims to promote data portability. Of course, it includes OpenID and OAuth with respect to authentication and authorization data portability. I am not sure which ones will survive and stand out  eventually, but this is a good signal that data portability is being considered as a critical issue and I hope it will be addressed in the near future.