Important OAuth signing changes coming to a container near you
April 1st, 2009 | Published in Google OpenSocial
Although OAuth and OpenSocial make a powerful combination, it's important for developers to know specific implementation details for each container. If you're a developer using the OpenSocial REST and RPC protocols, either with the client libraries or by rolling-your-own implementation, we wanted to let you know about two fundamental changes coming to Shindig which are intended to simplify the implementation and use of OAuth.
First, using content-type: application/x-www-form-urlencoded in any client to server requests will be strictly prohibited. Instead, we recommend using application/json, application/xml, or application/atom+xml.
Second, in addition to the current method of body signing (which treats the entire body as a query parameter), a new implementation will be made available called the request body hash. Developers should use one method or the other, not both, on any given request. When available, the client libraries will default to using the request body hash.
Here's a bit of background on these changes:
In order to verify that requests sent by developers to OpenSocial containers are actually coming from a trusted source, they are cryptographically signed. The container verifies signature to check that the request originated from the developer and to ensure that the details of the request have not been intercepted or modified by a third party.
In most cases, this turns out just fine, but incompatibilities and inconsistencies arise when you happen to send a request containing "&" or "=" characters in the body, such as this request to update appdata:
[{"params":{"groupId":"@self","appId":"@app","userId":"@viewer","data":{"testkey":"a=b&b=c"},"fields":"testkey"},"id":"add","method":"appdata.update"}]
When such a body is sent along with a content-type of application/x-www-form-urlencoded, Java Shindig (following the Java servlet spec) assumes that the "&" and "=" characters delineate key/value pairs of form data (it's x-www-form-urlencoded after all). When these parameters are reordered and put together as part of the OAuth signing process, the new signature will not match the one sent by the developer (who treats the request body as one giant parameter instead of several, as intended). Thus, the request fails.
However, when the content-type of the request body is properly disclosed (application/json in this case), Java Shindig will treat the body as one parameter, thereby avoiding any conflicts with either the spec or the "&" and "=" characters. In addition, support for the request body hash does away with the non-standard behavior of putting the request body into the signature base string, substituting a hash in its place. It's quite elegant, and far simpler from an implementation standpoint.
For more history and discussion, see this thread in the OpenSocial and gadgets spec group.
What this means for you as a developer:
If you've been dreading the part where I say "go implement this in your code," fear not. We've released new versions of each of the client libraries (Java, PHP, Python, Ruby) which support the changes, while maintaining backwards compatibility.
Starting today, the iGoogle and orkut sandboxes are incorporating these changes to let you start testing right away
If you have any questions on the client library changes, feel free to ask in the client libraries group.
First, using content-type: application/x-www-form-urlencoded in any client to server requests will be strictly prohibited. Instead, we recommend using application/json, application/xml, or application/atom+xml.
Second, in addition to the current method of body signing (which treats the entire body as a query parameter), a new implementation will be made available called the request body hash. Developers should use one method or the other, not both, on any given request. When available, the client libraries will default to using the request body hash.
Here's a bit of background on these changes:
In order to verify that requests sent by developers to OpenSocial containers are actually coming from a trusted source, they are cryptographically signed. The container verifies signature to check that the request originated from the developer and to ensure that the details of the request have not been intercepted or modified by a third party.
In most cases, this turns out just fine, but incompatibilities and inconsistencies arise when you happen to send a request containing "&" or "=" characters in the body, such as this request to update appdata:
[{"params":{"groupId":"@self","appId":"@app","userId":"@viewer","data":{"testkey":"a=b&b=c"},"fields":"testkey"},"id":"add","method":"appdata.update"}]
When such a body is sent along with a content-type of application/x-www-form-urlencoded, Java Shindig (following the Java servlet spec) assumes that the "&" and "=" characters delineate key/value pairs of form data (it's x-www-form-urlencoded after all). When these parameters are reordered and put together as part of the OAuth signing process, the new signature will not match the one sent by the developer (who treats the request body as one giant parameter instead of several, as intended). Thus, the request fails.
However, when the content-type of the request body is properly disclosed (application/json in this case), Java Shindig will treat the body as one parameter, thereby avoiding any conflicts with either the spec or the "&" and "=" characters. In addition, support for the request body hash does away with the non-standard behavior of putting the request body into the signature base string, substituting a hash in its place. It's quite elegant, and far simpler from an implementation standpoint.
For more history and discussion, see this thread in the OpenSocial and gadgets spec group.
What this means for you as a developer:
If you've been dreading the part where I say "go implement this in your code," fear not. We've released new versions of each of the client libraries (Java, PHP, Python, Ruby) which support the changes, while maintaining backwards compatibility.
Starting today, the iGoogle and orkut sandboxes are incorporating these changes to let you start testing right away
If you have any questions on the client library changes, feel free to ask in the client libraries group.