README

Sample extension to demonstrate integration with an OAuth service.

Overview
--------
This sample demonstrates the use of OAuth to authorize against 
Google's Contacts API inside of an extension.  It implements a library which
may be reused generically to authorize requests to any 3-legged OAuth API.

Library
-------
The library files are:
 * chrome_ex_oauth.html
 * chrome_ex_oauth.js
 * chrome_ex_oauthsimple.js

To use these files, place them in the root of your extension and include both
.js files in your background page in the following order:

  <script type="text/javascript" src="chrome_ex_oauthsimple.js"></script>
  <script type="text/javascript" src="chrome_ex_oauth.js"></script>   
  
To initialize the API, create a ChromeExOAuth object in the background page:

      var oauth = ChromeExOAuth.initBackgroundPage({
        'request_url'     :  <OAuth request URL>, 
        'authorize_url'   :  <OAuth authorize URL>,  
        'access_url'      :  <OAuth access token URL>,  
        'consumer_key'    :  <OAuth consumer key>,  
        'consumer_secret' :  <OAuth consumer secret>,  
        'scope'           :  <scope parameter for this auth>,
        'app_name'        :  <application name, not used by all OAuth providers>
      }); 

Call the authorize() function to redirect the user to the OAuth provider in
order to obtain an access token.  The client library abstracts most of this 
process, so all you need to do is pass a callback to the authorize() function
and a new tab will open and redirect the user.  If the library already has
stored an access token for the current scope, then no tab will be opened.  In
either case, the callback will be called with the resulting token and secret.

      oauth.authorize(onAuthorized);
      
There is no need to store the token and secret, as this library already stores
these values in localStorage.  Once the callback you specified is called, you
can call the sendSignedRequest function to send OAuth-signed requests to the
API.  The sendSignedRequest call takes an url to fetch, a callback function,
and an optional parameter object as its arguments.  The callback is passed
the response text as well as the XMLHttpRequest object which was used to 
make the request as its arguments.
  
      function callback(text, xhr) {
        //...
      };
      
      function onAuthorized() { 
        var url = <API url inside of the requested scope>;
        var request = {
          'method' : 'GET',
          'parameters' : {
             <Any request parameters as key : value pairs>
          }
        }
        oauth.sendSignedRequest(url, callback, request);
      };
      oauth.authorize(onAuthorized);