May 24
Delegated identity verification for uploadAndPost (OAuth Echo for uploadAndPost)
OAuth Echo was born out of the need to delegate identity verification — it's answering the question "how do you prove your identity to a third party service?". This is becoming really important given that @twitterapi is shutting down basic auth pretty soon. However, we just focused on getting the upload use case working (based on TwitPic API). We, unfortunately, didn't focus on uploadAndPost at all. The nice thing about uploadAndPost is that it is "fire and forget" API. Processing the uploaded item may take some time, and with the API it can be done asynchronously from the Twitter client application. So, it's time to specify how uploadAndPost will work.
(Note: this post is going to be specifically for Twitter, however, I am generalizing this enough so that it can be used by other services easily. I'll post a more generic specification at a future date).
As per my previous posts on OAuth Echo, there are four parties involved:
- 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 Delegator, or the 3rd party media provider; and
- the Service Provider a.k.a. Twitter.
The challenge with uploadAndPost is that it requires the text that is being posted from the Consumer be mutated on its way to the Service Provider:
- the user wants to send a photo up to a media provider along with a "caption" for it;
- the Delegator will store the photo, then generate a URL with it; and
- the Delegator will send up to the Service Provider the caption with the URL appended to it.
However, the Consumer has a problem because it is charged with generating the signature, but it doesn't know the final caption for the signature because it doesn't know the URL. This means Twitter is going to need to do some work.
So, here it goes: User wants to upload a photo. The Consumer is going to call uploadAndPost on the Delegator with a POST. The POST should contain the image, but it should also contain two or three additional items as headers or as POST parameters (I apologise for the multiple names for some of the parameters — I'm attempting to clean up, in retrospect, the OAuth Echo parameters for upload):
- X-OAuth-Endpoint or X-Auth-Service-Provider (if using POST parameters, then x_oauth_endpoint or x_auth_service_provider) — effectively, this is the endpoint to call on Twitter. For example, this could be http://api.twitter.com/1/status/update.json;
- X-OAuth-Payload (x_oauth_payload) — optional, but needed if parameters need to be passed to the X-OAuth-Endpoint. These parameters should be form url encoded;
- X-OAuth-Authorization or X-Verify-Credentials-Authorization (x_oauth_authorization or x_verify_credentials_authorization) — Consumer should create all the OAuth parameters necessary so as to be able to make an OAuth request to X-OAuth-Endpoint with the X-OAuth-Payload. Effectively, if the Consumer were calling Twitter directly, then this would be the OAuth header that it would send along (e.g. it should look like 'OAuth oauth_consumer_key="...", oauth_token="...", oauth_signature_method="...", oauth_signature="...", oauth_timestamp="...", oauth_nonce="...", oauth_version="..."')
The Delegator, at this point, presumably, needs to generate a URL for the media that has been uploaded (whether or not it stores it at this point, is left up to the implementor). Unlike the upload case, the way the Delegator is presumably going to verify that the media should be stored is whether or not calling the X-OAuth-Endpoint succeeds (if the call is denied due to bad credentials or for any other reason the call may have been denied, the Delegator will, presumably, drop the image).
To continue the call chain, the Delegator should call what was specified in X-OAuth-Endpoint (presumably, it should verify that it is a Twitter.com endpoint and it is not simply being asked to call arbitrary URLs on the web), and it should take the value passed in X-OAuth-Authorization to use in its Authorization header. To specify the URL to append to the message, it should also include a X-OAuth-Append-Payload header and Twitter will append that message to the end of the status text in the case of calling http://api.twitter.com/1/status/update.json.
This is not yet implemented on the Twitter side, but it will hopefully be soon. I'm definitely soliciting feedback.
At Twitgoo I had the idea about using a templated message - one could put a placeholder in the message where the url would be inserted. I've not implemented it yet, but obviously that wont work with this append payload as is.
I wonder though could a template/parameter system be employed here? The user application would sign the template, and the parameters would be passed along to fill in the template later. This could be maybe more easily extended to other methods that may be useful to have some form of Echo. To that point, how will this work with Annotations? I'm keen to come up with a media attachment standard and post tweets with those annotations
In your idea for the Append parameter, would that value be validated in any form? Must it be a URL?
Glad to see this progressing!
Let's say the call to the Twitter endpoint fails because of Rate limit. Now the delegator has no way to post the update without getting a second authorisation from the consumer.
It complicates the handshake logic too much, between the consumer and delegator.
Another question is from which API rate quota will the call be deducted against. User's, consumer's, delegator's ?
If it is the delegator's, there is still hope that the handshake complexity I mentioned above can be reduced, since the delegator than delay making the update until it is sure it will go through.
...since the delegator "can" delay making the update until it is sure it will go through.
does anybody have any suggestions as to what to do? i mean, we could
just allow the middle party to add any annotation it wants, but i
wonder whether that's a spam vector.
Please help :) Thanks