OAuth Proxy
The documentation on this feature has moved to http://code.google.com/apis/gadgets/docs/oauth.html
OLDER DOCUMENTATION
What is the OAuth Proxy?
Many Internet services are beginning to offer REST APIs that give access to the private data they store on behalf of a user, for example their photos, mail, address book, health records, etc. OAuth is a standard to allow the account owner of that data to tell the hosting service that it should allow another website (or gadget), to access that data. The OAuth Proxy is designed to make it easier for gadgets to use the OAuth standard (there are also slides available showing the data flow for the OAuth Proxy). If your company would like to learn more about why and how to become OAuth enabled, you can review this OAuth guide.
What websites provide containers support gadgets and the OAuth Proxy?
Currently the iGoogle sandbox is a gadget container that supports this feature. However there is an open-source project called Shindig which is an implementation of the gadget specification as well as the OAuth Proxy feature. Many other Internet websites are evaluating deploying this technology.
What Internet services have REST APIs that support OAuth?
It is supported by all of the REST APIs available from Google (see OAuth and Data API docs) as well as MySpace's Data Availability APIs. The OAuth community wiki lists additional service providers that provide OAuth enabled APIs.
What gadgets use the OAuth Proxy that I can try out?
Try the following walkthroughs of a MySpace gadget and a Google gadget.
How do I get started?
If you are building a gadget to access the REST APIs exposed by the Google Data "GData" APIs, then refer to the GData Gadget guide. Otherwise refer to the instructions below.
Step 1
Make a copy of the following sample gadget.
Step 2
Change all of the URLs in the OAuth section to use the endpoints defined by the OAuth service provider to which you are connecting. For example, for MySpace use the following:
<OAuth>
<Service name="myspace">
<Access url="http://api.myspace.com/access_token"/>
<Request url="http://api.myspace.com/request_token"/>
<Authorization url="http://api.myspace.com/authorize?oauth_callback=http://igdev.myspace.com/gadget/Auth.htm"/>
</Service>
</OAuth>
There is some public documentation on these parameters in the Gadgets API reference for the makerequest function that supports the OAuth signature option. If you want to learn more about makerequest, you can read the original documentation as well as some enhancements there were made to it to support the OpenSocial platform.
Step 3
If you are accessing a non-Google endpoint, then they generally will require you to register your application with them (for example see the MySpace registration), and they will provide you with a shared secret that is used to digitally sign all the requests from your application to the service provider. One problem with gadgets is that they are publicly accessible, so they are not a good place to store these types of secrets. Instead, you can register the shared secret with the website who provides the container in which your gadget will run, assuming they offer an OAuth Proxy. In the case of the iGoogle sandbox, you can send mail to oauthproxyreg@google.com with the following information to register your shared secret:
URL of your gadget
The shared secret assigned to you by the service provider
The consumer key assigned to you by the service provider
Whether to use symmetric or asymmetric signing with the service provider (or say that you don't know)
Until your shared secret has been registered, your gadget will not work. If you change the URL of your gadget, you will need to re-register the secret for that gadget.
Note to OAuth service providers: If you want to help your development community avoid this manual registration step, you can instead look for a digital signature in the OAuth requests from the iGoogle proxy using the drat OAuth Gadgets Extension. That signature verifies it came from Google, and provides the URL of the gadget on whose behalf the request is being made. The iGoogle sandbox uses the following public key (here presented as a self-signed certificate that should be be easily importable into OAuth libraries implemented in various programming languages):
-----BEGIN CERTIFICATE-----
MIICDzCCAXigAwIBAgIJAK4EbDB8Vz3kMA0GCSqGSIb3DQEBBQUAMBAxDjAMBgNV
BAMTBW9ya3V0MB4XDTA4MDQyNDE2NTU0NloXDTExMDExOTE2NTU0NlowEDEOMAwG
A1UEAxMFb3JrdXQwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBANw7NrXUteUP
ODxt+VDmUq01X2jzMYFofY2mc6AOddR9LKoadfn+2zhqMEoPno/h4/a8cZkPUjTv
Wi17rD17E69ZuPMzbysz0FAjeMaYUbc4tudNE8/QgsM24h6D4VDtKA4VcG8RHaxS
NoMN3P5I92Mzs5jVb/6GmAeGN7kRpUDhAgMBAAGjcTBvMB0GA1UdDgQWBBRfKFH0
1VbaxYc0GTuyvKk62+yx/TBABgNVHSMEOTA3gBRfKFH01VbaxYc0GTuyvKk62+yx
/aEUpBIwEDEOMAwGA1UEAxMFb3JrdXSCCQCuBGwwfFc95DAMBgNVHRMEBTADAQH/
MA0GCSqGSIb3DQEBBQUAA4GBABRLPFsM/etH7pQpez80LGNETfciOFpD3Uk6DdRE
GRiBpVC7eReb7O8BjyV7VNaGveqNSBI/XMfKORjzG3XsSq5e30H0VwRK7TNXgIc9
dTgWMqNiXTYxIjtmo5TogvFmspX56CBXbuJH/oeKYBM4oDWBMX6h0Su6CucAG0aC
xDB+
-----END CERTIFICATE-----
Step 4
In the FetchData function of the sample gadget, change the URL parameter so that it calls the desired REST function endpoint. This is frequently the same as the request_url defined in step 2, but you might add additional parameters such as requesting the results in JSON format.
Step 5
Modify the ShowResults function of the sample gadget to parse the data returned by the REST function and display the results in some basic way so you can confirm the gadget is properly communicating with the REST endpoint. The sample gadget expects to get an ATOM XML result in JSON format, and it iterates through looking for the “entry.gd$email[0].address” value. However if that is not the form you expect, then you will need to change this function.
Step 6
Your gadget should now work and get data from the OAuth endpoint. However the user who adds the gadget will need to go through the web page workflow required to approve your gadget's access to their data. You can then start customizing the gadget as needed to create the desired user experience.
How can the user experience be optimized?
One common complaint is that the workflow that an end-user must go through to approve the OAuth request is not very clean. Some OAuth service providers will let your gadget pass a continueURL parameter that tells the service provider where to send the user after they have approved the token. In addition, some gadget containers support a URL that will force the user to be redirected to a specific gadget instance. Thus you can pass that URL as the continueURL. For example, here are examples of the URL format you would use with some Google containers:
For iGoogle: TBD
For orkut: http://sandbox.orkut.com/Application.aspx?uid=16106640322329497443&appId=112386189666&bpc=1
If you are a developer who works for an OAuth enabled service provider, you might want to promote the gadget on your site. In that case, it would be strange to send the user from your site over to a gadget container, and then have them come back to your site to approve the OAuth access request. One advanced option you can try is to create a pre-approved request token and pass it as a parameter to the gadget. TBD