OAuth – Cast Iron Implementation

Brief introduction to the OAuth 1.0 (based on oauth.net Oauth 1.0 specification).

The OAuth protocol enables websites or applications (Consumers) to access Protected Resources from a web service (Service Provider) via an API, without requiring Users to disclose their Service Provider credentials to the Consumers.

The main benefit of OAuth implementation is that OAuth allows users to hand out tokens instead of credentials to their data hosted by a given service provider. Each token grants access to a specific site (e.g., a video editing site) for specific resources (e.g., just videos from a specific album) and for a defined duration (e.g., the next 2 hours). This allows a user to grant a third party site access to their information stored with another service provider, without sharing their access permissions or the full extent of their data.

 

OAuth by Example.

As an example  to benefits of OAuth implementation we’ll look at a scenario in which two applications A and B require access to user’s Google domain in order to create Google Documents, during data migration to Google Docs. Both application require the same access level to user’s Google Apps Account, yet we will see that application A, that doesn’t use OAuth, impose a higher security risk for the user than OAuth-enabled application B.

In order to be able to create document in the user’s Google Docs, application A needs to obtain user’s credentials  for Google Apps, whereas application B is registered to obtain the access token to Google Docs only.

At the end of the engagement (the migration process) the user revokes the access token of application B and sends the requests to the application A to securely dispose user’s credentials.

In order to understand the benefits of OAuth implementation, let’s measure the security exposure of the user to applications A and B during the migration process and after it ended.

Application A (non-OAuth) – even though the application had to access Google Docs only, by obtaining user’s Google Apps credentials, it  potentially gained access to the whole Google Apps suite (Gmail, Calendar, Groups, etc.).  At the end of the engagement, the user   has to trust the application A to dispose her credentials securely. After exposing her credentials to the application the user doesn’t have an absolute guarantee that the credentials haven’t been obtained (intentionally or unintentionally) by other party.

Application B (OAuth) – the application has to access the Google Docs only. As the user has full control of the access scope which is available to the application, she can specify the Google Docs scope for the application B, limiting the access of the application to Google Docs only. At the end of the engagement the user revokes the access of the application to Google Docs. The user has an absolute guarantee that the application B could not access the Google Docs anymore.

Even in this simple example we can see that although the access and functional scope of both applications to the user’s Google Apps Account was identical – namely Google Docs, user’s exposure to application A was much higher and is much harder to revoke. If the user has any doubts about the creditability of the Application A, the only solution is to change her Google credentials, potentially breaking the links to other clients that have her “old” credentials.

 

How it works.

OAuth comes in two flavours: 2-legged  OAuth and 3-legged OAuth.

2-legged  OAuth is much lighter than 3-legged OAuth and it doesn’t involve human involvement, and as such can be completely automated. The main drawbacks of 2-legged version is that it’s coarse grained (the access is on domain base rather than on personal user base), and much less documented and supported (Google Apps provide a very convenient playground for testing and developing 3-legged applications, but it doesn’t provide a playground for 2-legged version).

2-legged OAuth provides authentication for the entire domain. Once the administrator of the domain authorized 2-legged OAuth access for a set of API’s, and provides the OAuth Consumer Key (Client ID) and the OAuth Consumer Secret (Client Secret) to an application, the application can access the authorized set of API’s as any other user in the domain.

2-legged OAuth Authentication is done in two steps:

1.   The administrator of the Google account have to register the Consumer application with Google Apps. Once the application is registered, the generated Client ID and Client secret are obtained.

2.   The Consumer uses the Client Secret to sign the request to access the protected resource.

3-legged OAuth provides a fine grained access ( per individual user) and involves the user in the authorization process. Thus this protocol can not be completely automated. This protocol is widely supported (comparing to 2-legged) and well documented. This protocol is more complex than 2-legged version, since in addition to the 2-legged functionality it has a token negotiation and user verification steps.

 

3-legged OAuth Authentication is done in three steps:

1.    The Consumer obtains an unauthorized Request Token.

2.    The User authorizes the Request Token.

3.     The Consumer exchanges the Request Token for an Access Token. This Access Token enables the Consumer to access the     protected resource.

 

In the next paragraphs we will focus on  more detailed approaches to implementation of 2-legged and 3-legged protocols with IBM Cast Iron tool.

 

A Pseudo code of 3-legged OAuth implementation using IBM Cast Iron.

Please notice: All the requests involved in the OAuth process required to be signed by the corresponding consumer secret and token secret ( OAuth Core 1.0 Specification can be found in http://oauth.net/core/1.0/#signing_process ).  In order to sign the requests we will use the ‘Generate RFC2104 HMAC Compliant Signature’ function.

We will use IBM Cast Iron’s ability to expose and consume web services to implement the algorithm as a service.

 

The first run of the application differs from the subsequent runs.

First run:

The external request for accessing the protected resource  hits the façade web service. Since it’s a first run of the application, the device doesn’t hold an access token for the requested application, thus the request is issued for obtaining the request token, and after the user authorization of the request token, the subsequent request to retrieve access token is sent. The access token is being retrieved and saved on the device for the use of subsequent calls. The access token is used for accessing the protected resource.

Subsequent run:

The external request for accessing the protected resource  hits the façade web service. The access token, that has been stored previously on the device is retrieved and is used for accessing the protected resource.

 

 

 

The façade service encapsulates the following services:

• InitializeFlow                                    –  this web service runs only once, provided with the Client ID and the client secret of the registered application, the web service returns the Request Token to the user (step 1).
• RetrieveAccessToken                      –  this web service checks if the access token for the specified application exist in the system.

if access token doesn’t exist  (first run of the web service)  –  exchanges the request token for the access token (step 3) and store it in the system.

if access token exist (normal flow of the web service)   –   call the   AccessProtectedURL  web service with the access token

• AccessProtectedResource             –  this web service, provided with the access token, access the protected resource.

 

 

A Sketch of 2-legged OAuth implementation using IBM Cast Iron.