OAuth Echo

OAuth Echo

OAuth Echo is a means to securely delegate OAuth authorization with a third party while interacting with an API.

There are four parties involved in this interaction:

  • the User who is using Twitter through a particular, authorized Twitter 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
  • the Service Provider a.k.a. Twitter itself
     

Essentially, prepare a request for the delegator to send to the Twitter API on behalf of an application and a user. Add what would otherwise be a signed OAuth request into an HTTP header and ask the delegator to send that request to Twitter after completing the intermediary operation.

Here’s an example: 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 HTTP headers:

  • x-auth-service-provider — effectively, this is the realm that identity delegation should be sent to — in the case of Twitter, set this to https://api.x.com/1.1/account/verify_credentials.json. iOS5-based Twitter integrations will add an additional application_id parameter to this URL that will also be used to calculate the oauth_signature used in x-verify-credentials-authorization.
  • x-verify-credentials-authorization — Consumer should create all the OAuth parameters necessary so it could call https://api.x.com/1.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=”...” ).
     

Keep in mind that the entire transaction period needs to occur within an amount of time where the oauth_timestamp will still be valid.

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 — in this case, remember to escape and include the parameters in the OAuth signature base string — similar to encoding parameters in any request. It’s best to use HTTP headers to keep the operations as separate as possible.

The Delegators goal, at this point, is to verify that the User is who they say they are 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 the endpoint specified in the x-auth-service-provider header — in this case, https://api.x.com/1.1/account/verify_credentials.json, using the same OAuth authentication header provided by the Consumer in the x-verify-credentials-authorization header.
 

OAuth Echo best practices

Use the URL provided by x-auth-service-provider to perform the lookup, not a hard-coded value. Apple iOS, for example, adds an additional application_id parameter to all OAuth requests, and its existence should be maintained at each stage of OAuth Echo.

For the OAuth authorization portion, take the header value in x-verify-credentials-authorization, and place that into its own Authorization header for its call to the service provider. For good measure, confirm that the value in x-auth-service-provider is what it should be.

  • If the Service Provider returns an HTTP 200, then good. The Delegator should permanently store the image, generate a URL, and return it.
  • If the Service Provider doesn’t return an HTTP 200, then dump the image, and then return an error back to the Consumer.