Aug 27 2013

2-legged OAuth Java client made easy

Some scenario

When you build up your RESTful web API, there comes a time when authorization comes in the game. You need to provide means to restrict and control the access to your protected resources.
One of the most popular approaches involves the use of OAuth, an open authorization protocol (in its 1.0 version, than a framework in its 2.0 counterpart) that puts simplicity and security as part of its main goals.
I will not spend time discussing the good and the bad of OAuth, or the large controversy around the development of the version 2.0. I’d like instead to focus on how to secure your API without losing your mind around the potential complexities of OAuth.

A good and nowadays fairly recognized approach to deal with this is the so-called 2-legged OAuth. For the details, I invite you to check the excellent article Designing a Secure REST (Web) API without OAuth. Don’t get confused by the title, the author describes the authorization methodology applied by Amazon for its AWS API which is basically identical to 2-legged OAuth, the latter being only a bit more restrictive on some protocol aspects (i.e. the hash algorithm, the order of the parameters to be hashed).

How do we test our 2-legged OAuth-enabled service?

Implementing a proper OAuth authorization system is beyond the scope of this article, so I’ll jump to the point in which your API (by your own OAuth service implementation or by the integration with one of the multiple third-party services that will provide it for you) is secured and ready to be tested.
At that point, you may find out that finding a good, working and simple enough example of an OAuth Java client may be harder than what you would expect.

Scribe, the simple OAuth Java library

For our tests we will use Scribe, a Java library that supports a number of famous APIs (Google, Facebook, Yahoo, etc) and is easily extendable. Having a walkthrough of the code of the library is immediate as the design is clean and simple.
The first step is to include the library into our project; if you’re using Maven, a simple add to your pom.xml file will do the job:

<dependency>
<groupId>org.scribe</groupId>
<artifactId>scribe</artifactId>
<version>1.3.5</version>
</dependency>

Issuing an API call through 2-legged OAuth then is a matter of a few lines of Java code:

1
2
3
4
5
6
7
8
9
10
11
12
13
OAuthService service = new ServiceBuilder()
   .provider(DummyAPIProvider.class)
   .apiKey("your-api-public-key")
   .apiSecret("your-api-secret-key")
   .build();
 
OAuthRequest request = new OAuthRequest(Verb.GET, "http://api.company.com/protected-resource/");
 
Token accessToken = new Token("", "");
service.signRequest(accessToken, request);
 
Response response = request.send();
System.out.println(response.getBody());

DummyAPIProvider is a class that extends org.scribe.builder.api.DefaultApi10a and implements all the abstract methods by simply returning null. Those methods are involved in the standard OAuth workflow (also called 3-legged) to retrieve and sign the request and access token, elements that are not needed in the 2-legged approach (as you can see, we are simply passing an empty access token).
Behind the scenes, Scribe will generate the HMAC hash using the request information and the API secret key provided, and will send it along with the original request itself. If everything goes well, you will see the content of your protected resource in the standard output.

About

Globetrotter Software Engineer. I try to conjugate where the ambitions lead me with an environment that makes me feel happy. I love sun and sea. My mind is always spinning, for good and for bad. I enjoy traveling and experiencing new places by being constantly surprised by things I would have never even conceived.

4 comments on “2-legged OAuth Java client made easy

  1. Pingback: eSart's blog » Blog Archive Implement your 2-legged OAuth server with Java Restlet

    • Dear Shawn,
      the provided code is fully runnable, you just need to

      • copy the code in a Java class
      • add scribe to your project, either as a Maven package in your pom.xml or as an external jar
      • create a DummyAPIProvider class that extends org.scribe.builder.api.DefaultApi10a and implements all the abstract methods by simply returning null

      Thanks!

      • Hi, Enrico,

        Thanks for your reply. When I say “runnable”, I mean the actual apiKey, secret, etc., have already been provided by the service provider, e.g. Twitter or any others. I have taken a look at the github homepage of Scribe. The “Get Started” example is using Twitter as the provider, but it seems to be the 3-legged approach, as well as without the actual key and secret … does that mean I have to register by myself ? have you already done that in your demo ? is it OK for me to use it directly ?

        Anyway, thanks for your time :-). Just eager to get the oauth client running … By the way, what about Jersey, have you used Jersey to do the same thing as Scribe ?

        shawn on said:

Leave a Reply

Your email address will not be published. Required fields are marked *