May 14
Guidelines for implementing OAuth Echo
According to my tally of questions people have been asking me regarding the basic auth removal date for @twitterapi are mostly skewing towards OAuth Echo — given that, let's try to standardize the flow in some prose. It would help if everybody implemented this the exact same way to make it easier on everybody else.
(Note: everything here is going to be specifically for Twitter and is based on the blog post I wrote a few months ago. Later, I'm both going to produce a more general document so that any service can implement OAuth Echo. Nobody should have to change anything going forward. Additionally, this is only for the upload case, and a following post will talk about uploadAndEcho.)
There are four parties involved in this interaction — the User who is using Twitter through a particular Twitter application (and, presumably, has already OAuthorized Twitter through that application); the Consumer, or the Twitter application that is attempting to interact with the 3rd party media provider (e.g. the photo sharing site) — the Consumer; the Delegator, or the 3rd party media provider; and the Service Provider a.k.a. Twitter itself.
So, let's go: the User wants to upload a photo. The Consumer is going to call upload on the Delegator with a POST. The POST should contain the image, but it should also contain two additional items as headers
- X-Auth-Service-Provider — effectively, this is the realm that identity delegation should be sent to — in the case of Twitter, just set this to https://api.twitter.com/1/account/verify_credentials.json;
- X-Verify-Credentials-Authorization — Consumer should create all the OAuth parameters necessary so it could call https://api.twitter.com/1/account/verify_credentials.json using OAuth in the HTTP header (e.g. it should look like OAuth oauth_consumer_key="...", oauth_token="...", oauth_signature_method="...", oauth_signature="...", oauth_timestamp="...", oauth_nonce="...", oauth_version="..." — the line breaks are for decoration only).
(Alternatively, instead of sending these two parameters in the header, they could be sent in the POST as x_auth_service_provider and x_verify_credentials_authorization — if you do this, then remember to escape.
The Delegator's goal, at this point, is to verify that the User is who he or she says he or she is before it saves the media. Once the Delegator receives all the data above via its upload method, it should temporarily store the image, and then construct a call to https://api.twitter.com/1/account/verify_credentials.json. For the OAuth authorization portion, it should take the value in X-Verify-Credentails-Authorization, and stick that into it's Authorization header for its call (probably, for good measure, it should confirm the value in X-Auth-Service-Provider is what it should be):
- If the Service Provider returns a HTTP 200, then we're good. The Delegator should permanently store the image, generate a URL, and return it.
- If the Service Provider doesn't return a HTTP 200, then dump the image, and then return an error back to the Consumer.
I hope that clears a bunch of stuff up. There are definitely some issues with this approach (e.g. the Delegator is holding and blocking a connection to the Consumer while it is talking to the Service Provider) — but, that's a problem with the way the upload method in the TwitPic API is specified. We can tackle making that better later.
Now, I'm off to write out the documents to support uploadAndPost.
