Heikniemi Hardcoded

Jouni Heikniemi's IT adventures

• Home
• About

Twitter and OAuth in desktop applications

If you’re into Twitter API programming, you probably know that the end of basic authentication is here. This post delves into the question of using the OAuth authentication mechanism in desktop applications. If you know the subject, this post will give you some practical advice for C# application development. If you don’t, it’ll act as a primer on OAuth for modern web sites.

The context: A typical application making use of Twitter or another web service almost always needs to act on behalf of a user. The need might be read-only (such as reading a user’s friends list or status history), or it might be read/write, such as with a Twitter client.

Why OAuth?

First, it is necessary to define OAuth and its place in the world as a step forward from basic authentication. When I say “basic authentication”, I mean the technology of sending the users’ credentials in an HTTP header, essentially in plain text.

This approach has three main caveats. First, intercepting the HTTP traffic allows the attacker full control of the user’s account. Second, the application needs to know and store the credentials for the user. Third, since the credentials by definition mean full control, there is no way to grant a limited permission set to an application. And a fourth minor thing, more an inconvenience, is the fact that when a user changes his password, he must change it in all the applications he is using.

The Twitter API has traditionally supported both basic and OAuth approaches, but basic authentication has now been deprecated. The preceding reasons are the main causes for this.

OAuth how?

OAuth, an open protocol designed for secure API usage, builds on a fundamentally different model. The following describes a basic exchange for OAuth-based authentication. In the exchange, three parties take a role: the user (a human being), the service (e.g. Twitter) and the consuming application (i.e. the code running on the user's behalf).

1. The user indicates his/her desire to use a given service provider, like Twitter.
2. The consuming application issues a request to the service, asking for an URI where to push the user for authorization.
3. The consuming application redirects the user to the authorization URI hosted within the service.
4. The service asks the user for permission. See the image to the right for an example of Twitter’s permission grant dialog. Note that a more granular permission dialog might contain checkboxes allowing the user to control the level of access to the application.
5. Once user clicks Allow, he is redirected back to the application; the URI contains a token that enables the application to authenticate.
6. All further API calls will be made with said authentication tokens, establishing user identity.

Details have been skipped and some mechanics may vary between services, but that’s the rough idea.

Note that one element this Twitter example presupposes is that the consuming application must be registered in beforehand. When any API calls are made, the consuming application always identifies itself, which identification Twitter then shows in the permission dialog. This makes it much harder for malicious apps to impersonate other applications. We’ll look at this in more detail shortly.

OAuth and desktop applications

The previous example had details that clearly show it was engineered for the web. For example, note the use of the word “redirect”. Works great if you’re in a browser context – and in fact, opening the permission grant dialog isn’t really a problem in any scenario, because the browser is readily available.

However, the step 5 is more of a problem. Unless the consuming application happens to be a web site, redirecting to it isn’t really possible. Well, most consuming applications work on the web, and that’s exactly the scenario OAuth has been designed for.

Yet still, there are quite a few applications that run on the desktop without a browser GUI. For these, the “redirection” must be done manually, by transferring the token through methods such as look-and-type or copy-and-paste.

xAuth then?

xAuth is a protocol that enables browserless token exchange, essentially simplifying the process to this: The application asks for user name and password and then calls an API that turns the username/password into authentication tokens.

xAuth thus provides a compromise between the values described earlier: The consuming application will get its hands on the username/password combination, but it doesn’t have to store them. If the application is benign, it will not misuse the credentials and will discard them right after getting the tokens (and storing them instead), thus bringing all of the OAuth benefits into play for the rest of the time. Malicious applications will, of course, be able to misuse the username/password combination.

Unfortunately, xAuth isn’t widely available for Twitter yet, and needs special activation by the Twitter API team. So, in the next example, we’re going to tackle this with OAuth. And while xAuth will probably become mainstream one day, the next steps will still be a valuable learning experience – xAuth is, after all, mostly a layer upon OAuth.

Twitter, OAuth and a console application

In the next example, I’m going to build a .NET console application that supports OAuth authentication, storing the authentication tokens in a local file store and then use them to allow the user to send tweets. Actually, the syntax help for the application is pretty informative of the application’s capabilities:

Syntax: TwitterOAuthDemo <command> <arguments>

Valid commands and arguments are:
  authenticate <accountIdentifier>
  tweet <accountIdentifier> <text>

A typical usage sequence is to call authenticate, which opens up a browser
that you can use to get the OAuth PIN, then enter the PIN into the console
window. Once done, you can use the tweet command to actually send
tweets. Since the OAuth access tokens are stored, you only need to call
authenticate once.

Note that the account identifiers are only strings used in this system. 
The OAuth system does not need to know the actual user account name. 
You can use whatever identifiers you want. The identifiers will get mapped 
to twitter usernames at the time of authentication.

For example:

TwitterOAuthDemo authenticate OurNewsInEnglish
TwitterOAuthDemo tweet OurNewsInEnglish "This is a hot news headline"

Ok, let’s look at how this works.

First of all, we must register the application. You do this by going into Twitter’s application registration page and entering some basic information. Perhaps the most important choice there is to denote the application as a Desktop app, so that Twitter will know to show the PIN instead of redirecting the user to another page.

When registered, you receive a pair of tokens for your application – essentially, a user name and a password. Whenever you want to access the service, you always need to authenticate yourself (the application). These tokens must be stored inside the application.

The created clientInfo object will then be passed on into each of the method calls made to the Twitter API. In this example, I will be using the TweetSharp library, which while having reached version 1.0, is also out of support by the original authors. However, until drastic changes occur with the Twitter API, it’ll work quite OK.

The authorization part

Like stated earlier on in the syntax help example, the application does not know the Twitter username of the account it uses. So, say the user gives a command of “TwitterOAuthDemo authenticate MyAccount”. The “MyAccount” part is just an identifier within the application, necessary mostly because typing the authentication tokens would be very cumbersome indeed. What happens next?

This step is required to get a token, a text string that identifies the forthcoming authentication request. Even though the result is wrapped in an OAuthToken, it’s really a pair of strings pretty much like the ConsumerKey and ConsumerSecret in the example above. Looking at the generated request in Fiddler, we see this (unnecessary pieces elided for readability):

GET http://api.twitter.com/oauth/request_token HTTP/1.1
Authorization: OAuth oauth_consumer_key="DQtmU4Gs3wiAlU3Qw...",
  oauth_nonce="l8hn3ftmxrnw4umd",
  oauth_signature="C2EHUSpCJOjtgeE5ObQybJ9Q8qg%3D"

Note that while the request does contain the consumer key, it does _not_ contain the consumer secret. Rather, the message is signed with the secret (again, skipping some less relevant details). Thus OAuth protects both the user and the application from having their identity stolen: this message could not be crafted without knowing the ConsumerSecret.

The HTTP response to this message contains a token (yet another string) and its secret. With the token received, we should get the user out to Twitter to grant us the permission. This operation is really nothing more than formatting an appropriate URI, although the TweetSharp API makes it look like a complex API call. With the URI prepared, we can redirect the user to the authorization page.

In this example, the URI opened by the default browser was http://api.twitter.com/oauth/authorize?oauth_token=pzvqEf1HybC4z… – i.e. it contained the token returned by the previous API call to request_token. Now, the user gets to see the authorization page shown earlier in this blog post. When he clicks Allow, he gets the PIN code he then can type into to the application.

With the PIN, we now use the original unauthorized token and the given PIN code to verify the login. The response to this request is an authorized token – again, essentially a pair of strings. Looking at this request in Fiddler (with nonrelevant parts sliced off):

GET http://api.twitter.com/oauth/access_token HTTP/1.1
Authorization: OAuth oauth_consumer_key="DQtmU4Gs3wiAlU3Qw...",
  oauth_token="pzvqEf1HybC4zD7MbIqiJzuuAMnsyqmQrsb1WdzOVbE",
  oauth_signature="jJ%2BEYt72JT548tZsTNw725Er5Ko%3D",
  oauth_verifier="8771529"

For a response, we get (headers removed):

oauth_token=185590444-Z4PWQNxM4PnoWMZfAXhJMOgjA0alTy8d2s3QVJv6&
oauth_token_secret=SxMO9duioXhRcpf1llXWdppEdAEIqgYfE9APrpQcjc

It is now this pair of strings we need to store for future use and pass them in each of our requests.

Next, we store them locally. There is a hand-written TokenStore class for this purpose, but its implementation is irrelevant and needs no revising here. Check out the source package if you’re interested.

Tweeting with the credentials

With the OAuth credentials stored, we can now use them to create requests. The Tweet method thus becomes extremely simple, the core being this:

While the clientInfo structure contains the identity of the application, it is the AuthenticateWith call that specifies the user credentials. But again, note that the application only stores the oauth_token and oauth_token_secret – it does not store or even know the username. The account identifiers are only used as easy-to-type names for tokens inside the application – Twitter knows nothing about them.

Look at the request at the HTTP level:

POST http://api.twitter.com/1/statuses/update.json HTTP/1.1
Authorization: OAuth oauth_consumer_key="DQtmU4Gs3wiAlU3Qw...",
  oauth_token="185590444-Z4PWQNxM...",
  oauth_signature="opZPjnyd1PQg2tz%2FEd1hhPi95po%3D"

status=ThisIsMyNewStatus

As you can see, the oauth_token_secret is not conveyed in the request, but again, rather used as a part in signing the message. Thus, anyone capturing this request could not use it to hijack the application’s access to the user’s account.

Where’s the source?

Here, go get it. The source compiles to a fully functional executable with two additions: First, you need to download TweetSharp and fix the references in the project, and second, you must register your application in Twitter, then fill in the OAuth consumer key and secret from the Twitter site to the initialization of the ClientInfo structure (the source has my test app’s keys removed).

Have fun!

September 2, 2010 · Jouni Heikniemi · 10 Comments
Tags: OAuth, Twitter · Posted in: .NET, Web

• « Previous post
• Next post »

• Categories

  • .NET
  • Bugzilla
  • Cloud
  • Entrepreneurship
  • General
  • Information Worker
  • Misc. programming
  • Web
  • Windows IT

• Archives

  • April 2016
  • January 2016
  • August 2015
  • April 2015
  • March 2015
  • February 2015
  • December 2013
  • June 2013
  • June 2012
  • May 2012
  • March 2012
  • January 2012
  • November 2011
  • October 2011
  • September 2011
  • June 2011
  • May 2011
  • April 2011
  • January 2011
  • December 2010
  • November 2010
  • October 2010
  • September 2010
  • August 2010
  • July 2010
  • June 2010
  • May 2010
  • April 2010
  • March 2010
  • February 2010
  • January 2010
  • December 2009
  • November 2009
  • October 2009
  • September 2009
  • August 2009
  • July 2009
  • June 2009
  • January 2007
  • December 2006
  • November 2006
  • October 2006
  • September 2006
  • August 2006
  • December 2005
  • September 2005
  • August 2005
  • July 2005
  • June 2005
  • May 2005
  • April 2005
  • March 2005
  • February 2005
  • January 2005
  • December 2004
  • November 2004
  • October 2004
  • September 2004
  • August 2004
  • July 2004

• Meta

  • Log in
  • Entries RSS
  • Comments RSS