Sending messages to Twitter from any application is straightforward, if you follow the protocol.  The problem is, Twitter does not explicitly define the protocol in any one place.

If you go to the developer center on Twitter’s site, there is a section that deals with how Twitter uses OAuth (which is defined in IETF RFC 5849), but Twitter doesn’t explain exactly how.  Instead, Twitter refers to external sources (one, two) for the definition of the general OAuth protocol, and it expends a bunch of effort explaining why apps cannot use Basic Auth.  Not helpful for an implementer. Twitter’s doc page then points developers to existing third-party OAuth libraries.  There is no documentation that I could find that explicitly describes or demonstrates what I would call the communications protocol: the message flows required to use OAuth to connect to Twitter, for the various scenarios – a web application, a “traditional” desktop app, a mobile app, and so on.

Beyond the communication protocol, there is no firm guidance from Twitter on User Interface models – what an application should look like or do.  There is no firm guidance around the issues surrounding the OAuth consumer keys and secret keys.

For various reasons a developer might want more detailed information.  For one thing, the developer may be developing their own Twitter-friendly library, for various reasons: licensing or other intellectual property concerns, efficiency, control.  If you are developing your own application that uses Twitter, the upshot is: the implementation is the documentation. Twitter provides some reference material, but it is not complete; when you get down to it, you need to try and see. Develop, test, diagnose, see what works. Developers will have to figure it out themselves.

I went through that process with a couple of applications based in C#, and here’s what I learned.  The basics:

1. OAuth isn’t mysterious or mystical. It’s well-defined. Using the protocol with Twitter requires some exploration.
2. OAuth defines 3 parties to the transaction: a server, a client, and a resource owner. The server is the manager of resources; in the case of Twitter, twitter is the server.  The resource owner is the user.  The client is the application that the user employs to connect to the server – for example, something that posts Tweets on behalf of a user. This can be a web application (another server), a desktop application, a mobile phone app, and so on.
3. All OAuth 1.0 clients (and remember, client = application) have an associated “consumer key” and  “consumer secret”.  In later drafts of OAuth 1.0 these were together termed “client credentials”.  When a developer builds an app, he registers it with the OAuth provider – in this case, Twitter – and receives those two opaque strings. As part of the OAuth protocol, the application (aka client) sends the consumer key to Twitter at runtime, encrypted with his consumer secret, in order to identify itself. If Twitter can decrypt the message with the copy of the secret it holds in association to that consumer key, Twitter concludes the client to be authentic.
4. When the client (application) identifies itself to Twitter, Twitter checks to see if the client is authorized to act on behalf of the user or “resource owner”.  If not, Twitter instructs the client to tell the user to approve the client for this interaction, via a web page interaction. In other words, Twitter tells the client, “Have the user visit this web page…” and when the client does so, Twitter asks the user, “Do you approve this app?”.  For this approval, the user (resource owner) must authenticate directly to Twitter with his username and password, and can then reply yes or no.  With an affirmative reply, Twitter marks the client (really, the application, identified by the consumer key it presents to Twitter) as authorized to act on behalf of this particular user.
5. Now that the client is identified and authorized, it can send requests to Twitter to update the resources on behalf of the resource owner. In simple terms: the app can post tweets to the user’s status stream.
6. If the user wants to later de-authorize the client application from acting on its behalf, it can visit Twitter.com to do so.

A Concern about Client Identity

The use of the consumer key or client credential as the basis for application identification means that the claimed identity of desktop applications cannot be trusted.  Here’s why:  OAuth assumes that an application that holds these credentials is the registered application.  Yet most traditional desktop or mobile applications will store this information in the compiled binary, or in some external store. This information will be accessible to other applications, which means the “client identity” can be easily forged, either mistakenly or on purpose. A developer just needs to grab those two items and embed them in a new app, and you’ve got a “stolen application identity” problem.  In short, anyone that uses a desktop application to connect to Twitter has the power to forge the identity of that application.  This is one of a set of concerns around Twitter’s use of OAuth, that have been previously articulated.  I don’t have a good answer for this problem.

In my next post I’ll describe the OAuth 1.0a protocol flows.