| OLD | NEW |
| 1 <h1>Tutorial: OAuth</h1> | 1 <h1>Tutorial: OAuth</h1> |
| 2 | 2 |
| 3 | 3 |
| 4 <p> | 4 <p> |
| 5 <a href="http://oauth.net/">OAuth</a> is an open protocol that aims to standardi
ze the way desktop and web applications access a user's private data. OAuth prov
ides a mechanism for users to grant access to private data without sharing their
private credentials (username/password). Many sites have started enabling APIs
to use OAuth because of its security and standard set of libraries. | 5 <a href="http://oauth.net/">OAuth</a> is an open protocol that aims to standardi
ze the way desktop and web applications access a user's private data. OAuth prov
ides a mechanism for users to grant access to private data without sharing their
private credentials (username/password). Many sites have started enabling APIs
to use OAuth because of its security and standard set of libraries. |
| 6 </p> | 6 </p> |
| 7 <p> | 7 <p> |
| 8 This tutorial will walk you through the necessary steps for creating a Google Ch
rome Extension that uses OAuth to access an API. It leverages a library that you
can reuse in your extensions. | 8 This tutorial will walk you through the necessary steps for creating a Google Ch
rome Extension that uses OAuth to access an API. It leverages a library that you
can reuse in your extensions. |
| 9 </p> | 9 </p> |
| 10 <p> | 10 <p> |
| 11 This tutorial uses the <a href="http://code.google.com/apis/documents/">Google D
ocuments List Data API</a> as an example OAuth-enabled API endpoint. | 11 This tutorial uses the <a href="http://code.google.com/apis/documents/">Google D
ocuments List Data API</a> as an example OAuth-enabled API endpoint. |
| 12 </p> | 12 </p> |
| 13 | 13 |
| 14 <h2 id="requirements">Requirements</h2> | 14 <h2 id="requirements">Requirements</h2> |
| 15 | 15 |
| 16 <p> | 16 <p> |
| 17 This tutorial expects that you have some experience writing extensions for Googl
e Chrome and some familiarity with the <a href="http://code.google.com/apis/acco
unts/docs/OAuth.html">3-legged OAuth</a> flow. Although you don’t need a backgro
und in the <a href="http://code.google.com/apis/documents/">Google Documents Lis
t Data API</a> (or the other <a href="http://code.google.com/apis/gdata/">Google
Data APIs</a> for that matter), having an understanding of the protocol may be
helpful. | 17 This tutorial expects that you have some experience writing extensions for Googl
e Chrome and some familiarity with the <a href="http://code.google.com/apis/acco
unts/docs/OAuth">3-legged OAuth</a> flow. Although you don’t need a background i
n the <a href="http://code.google.com/apis/documents/">Google Documents List Dat
a API</a> (or the other <a href="http://code.google.com/apis/gdata/">Google Data
APIs</a> for that matter), having an understanding of the protocol may be helpf
ul. |
| 18 </p> | 18 </p> |
| 19 | 19 |
| 20 <h2 id="getting-started">Getting started</h2> | 20 <h2 id="getting-started">Getting started</h2> |
| 21 | 21 |
| 22 <p> | 22 <p> |
| 23 First, copy the four library files from the Chromium source tree at <a href="htt
p://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examp
les/extensions/oauth_contacts/">.../examples/extensions/oauth_contacts/</a>: | 23 First, copy the four library files from the Chromium source tree at <a href="htt
p://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examp
les/extensions/oauth_contacts/">.../examples/extensions/oauth_contacts/</a>: |
| 24 </p> | 24 </p> |
| 25 <ul> | 25 <ul> |
| 26 <li><strong><a href="examples/extensions/oauth_contacts/chrome_ex_oauth.html" do
wnload="chrome_ex_oauth.html">chrome_ex_oauth.html</a></strong> - interstitial p
age for the oauth_callback URL</li> | 26 <li><strong><a href="examples/extensions/oauth_contacts/chrome_ex_oauth" downloa
d="chrome_ex_oauth">chrome_ex_oauth</a></strong> - interstitial page for the oau
th_callback URL</li> |
| 27 <li><strong><a href="examples/extensions/oauth_contacts/chrome_ex_oauth.js" down
load="chrome_ex_oauth.js">chrome_ex_oauth.js</a></strong> - core OAuth library</
li> | 27 <li><strong><a href="examples/extensions/oauth_contacts/chrome_ex_oauth.js" down
load="chrome_ex_oauth.js">chrome_ex_oauth.js</a></strong> - core OAuth library</
li> |
| 28 <li><strong><a href="examples/extensions/oauth_contacts/chrome_ex_oauthsimple.js
" download="chrome_ex_oauthsimple.js">chrome_ex_oauthsimple.js</a></strong> - he
lpful wrapper for chrome_ex_oauth.js</li> | 28 <li><strong><a href="examples/extensions/oauth_contacts/chrome_ex_oauthsimple.js
" download="chrome_ex_oauthsimple.js">chrome_ex_oauthsimple.js</a></strong> - he
lpful wrapper for chrome_ex_oauth.js</li> |
| 29 <li><strong><a href="examples/extensions/oauth_contacts/onload.js" download="onl
oad.js">onload.js</a></strong> - | 29 <li><strong><a href="examples/extensions/oauth_contacts/onload.js" download="onl
oad.js">onload.js</a></strong> - |
| 30 initializes chrome_ex_oauth.html and redirects the page if needed to start the O
Auth flow</li> | 30 initializes chrome_ex_oauth and redirects the page if needed to start the OAuth
flow</li> |
| 31 </ul> | 31 </ul> |
| 32 | 32 |
| 33 <p>Place the four library files in the root of your extension directory (or wher
ever your JavaScript is stored). Then include the .js files in your background p
age in the following order:</p> | 33 <p>Place the four library files in the root of your extension directory (or wher
ever your JavaScript is stored). Then include the .js files in your background p
age in the following order:</p> |
| 34 | 34 |
| 35 <pre> | 35 <pre> |
| 36 <script type="text/javascript" src="chrome_ex_oauthsimple.js"></script&
gt; | 36 <script type="text/javascript" src="chrome_ex_oauthsimple.js"></script&
gt; |
| 37 <script type="text/javascript" src="chrome_ex_oauth.js"></script> | 37 <script type="text/javascript" src="chrome_ex_oauth.js"></script> |
| 38 <script type="text/javascript" src="onload.js"></script> | 38 <script type="text/javascript" src="onload.js"></script> |
| 39 </pre> | 39 </pre> |
| 40 | 40 |
| 41 <p>Your background page will manage the OAuth flow.</p> | 41 <p>Your background page will manage the OAuth flow.</p> |
| 42 | 42 |
| 43 <h2 id="oauth-dance">The OAuth dance in an extension</h2> | 43 <h2 id="oauth-dance">The OAuth dance in an extension</h2> |
| 44 | 44 |
| 45 <p> | 45 <p> |
| 46 If you are familiar with the OAuth protocol, you'll recall that the OAuth dance
consists of three steps: | 46 If you are familiar with the OAuth protocol, you'll recall that the OAuth dance
consists of three steps: |
| 47 </p> | 47 </p> |
| 48 | 48 |
| 49 <ol> | 49 <ol> |
| 50 <li>fetching an initial request token</li> | 50 <li>fetching an initial request token</li> |
| 51 <li>having the user authorize the request token</li> | 51 <li>having the user authorize the request token</li> |
| 52 <li>fetching an access token</li> | 52 <li>fetching an access token</li> |
| 53 </ol> | 53 </ol> |
| 54 | 54 |
| 55 <p>In the context of an extension, this flow gets a bit tricky. Namely, there is
no established consumer key/secret between the service provider and the applica
tion. That is, there is no web application URL for the user to be redirected to
after the approval process. | 55 <p>In the context of an extension, this flow gets a bit tricky. Namely, there is
no established consumer key/secret between the service provider and the applica
tion. That is, there is no web application URL for the user to be redirected to
after the approval process. |
| 56 </p> | 56 </p> |
| 57 | 57 |
| 58 <p> | 58 <p> |
| 59 Luckily, Google and a few other companies have been working on an <a href="http:
//code.google.com/apis/accounts/docs/OAuthForInstalledApps.html">OAuth for insta
lled applications</a> solution that you can use from an extension environment. I
n the installed applications OAuth dance, the consumer key/secret are ‘anonymous
’/’anonymous’ and you provide an <em>application name</em> for the user to grant
access to (instead of an application URL). The end result is the same: your bac
kground page requests the initial token, opens a new tab to the approval page, a
nd finally makes the asynchronous call for the access token. | 59 Luckily, Google and a few other companies have been working on an <a href="http:
//code.google.com/apis/accounts/docs/OAuthForInstalledApps">OAuth for installed
applications</a> solution that you can use from an extension environment. In the
installed applications OAuth dance, the consumer key/secret are ‘anonymous’/’an
onymous’ and you provide an <em>application name</em> for the user to grant acce
ss to (instead of an application URL). The end result is the same: your backgrou
nd page requests the initial token, opens a new tab to the approval page, and fi
nally makes the asynchronous call for the access token. |
| 60 </p> | 60 </p> |
| 61 | 61 |
| 62 <h3 id="set-code">Setup code</h3> | 62 <h3 id="set-code">Setup code</h3> |
| 63 | 63 |
| 64 <p>To initialize the library, create a <code>ChromeExOAuth</code> object in the
background page:</p> | 64 <p>To initialize the library, create a <code>ChromeExOAuth</code> object in the
background page:</p> |
| 65 | 65 |
| 66 <pre> | 66 <pre> |
| 67 var oauth = ChromeExOAuth.initBackgroundPage({ | 67 var oauth = ChromeExOAuth.initBackgroundPage({ |
| 68 'request_url': <OAuth request URL>, | 68 'request_url': <OAuth request URL>, |
| 69 'authorize_url': <OAuth authorize URL>, | 69 'authorize_url': <OAuth authorize URL>, |
| (...skipping 15 matching lines...) Expand all Loading... |
| 85 'consumer_key': 'anonymous', | 85 'consumer_key': 'anonymous', |
| 86 'consumer_secret': 'anonymous', | 86 'consumer_secret': 'anonymous', |
| 87 'scope': 'https://docs.google.com/feeds/', | 87 'scope': 'https://docs.google.com/feeds/', |
| 88 'app_name': 'My Google Docs Extension' | 88 'app_name': 'My Google Docs Extension' |
| 89 }); | 89 }); |
| 90 </pre> | 90 </pre> |
| 91 | 91 |
| 92 <p> | 92 <p> |
| 93 To use the OAuth library, | 93 To use the OAuth library, |
| 94 you must declare the "tabs" permision in the | 94 you must declare the "tabs" permision in the |
| 95 <a href="manifest.html">extension manifest</a>. | 95 <a href="manifest">extension manifest</a>. |
| 96 You must also declare the sites you are using | 96 You must also declare the sites you are using |
| 97 including the request URL, the authorize URL, access URL, | 97 including the request URL, the authorize URL, access URL, |
| 98 and, if necessary, the scope URL. | 98 and, if necessary, the scope URL. |
| 99 For example: | 99 For example: |
| 100 </p> | 100 </p> |
| 101 | 101 |
| 102 <pre data-filename="manifest.json"> | 102 <pre data-filename="manifest.json"> |
| 103 "permissions": [ "tabs", "https://docs.google.com/feeds/*", | 103 "permissions": [ "tabs", "https://docs.google.com/feeds/*", |
| 104 "https://www.google.com/accounts/OAuthGetRequestToken", | 104 "https://www.google.com/accounts/OAuthGetRequestToken", |
| 105 "https://www.google.com/accounts/OAuthAuthorizeToken", | 105 "https://www.google.com/accounts/OAuthAuthorizeToken", |
| (...skipping 103 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 209 <h2 id="sample-code">Sample code</h2> | 209 <h2 id="sample-code">Sample code</h2> |
| 210 | 210 |
| 211 <p> | 211 <p> |
| 212 Sample extensions that use these techniques are available in the Chromium source
tree: | 212 Sample extensions that use these techniques are available in the Chromium source
tree: |
| 213 </p> | 213 </p> |
| 214 | 214 |
| 215 <ul> | 215 <ul> |
| 216 <li><a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/exten
sions/docs/examples/extensions/gdocs/">.../examples/extensions/gdocs/</a></li> | 216 <li><a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/exten
sions/docs/examples/extensions/gdocs/">.../examples/extensions/gdocs/</a></li> |
| 217 <li><a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/exten
sions/docs/examples/extensions/oauth_contacts/">.../examples/extensions/oauth_co
ntacts/</a></li> | 217 <li><a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/exten
sions/docs/examples/extensions/oauth_contacts/">.../examples/extensions/oauth_co
ntacts/</a></li> |
| 218 </ul> | 218 </ul> |
| OLD | NEW |