谷歌 APIs 使用 OAuth 2.0 協(xié)議來進(jìn)行驗(yàn)證和授權(quán)。谷歌支持常見的 OAuth 2.0 方案,例如 web 服務(wù)器使用的,本地安裝的,和客戶端方面的應(yīng)用。
首先,從谷歌開發(fā)者控制臺(tái)獲得 OAuth 2.0 客戶端憑證。然后您的客戶端應(yīng)用程序向谷歌授權(quán)服務(wù)器請(qǐng)求獲得一個(gè)訪問令牌,接下來從回應(yīng)中提取出令牌,并將其發(fā)送給你想要訪問的谷歌 API。 若想動(dòng)手演練如何通過 OAuth 2.0 訪問谷歌,您可以在 OAuth 2.0 游樂場(chǎng)里面做實(shí)驗(yàn)(您可以選擇使用自己的客戶端憑證)。
該頁面為您概要地展示各種谷歌支持的 OAuth 2.0 授權(quán)方案,并提供詳細(xì)內(nèi)容的鏈接。若想詳細(xì)了解關(guān)于如何使用 OAuth 2.0 來進(jìn)行驗(yàn)證,請(qǐng)參閱 OpenID 連接。
注意:由于能否正確實(shí)現(xiàn)該功能牽涉到安全問題,所以當(dāng)您和谷歌的 OAuth 2.0 端點(diǎn)進(jìn)行互動(dòng)時(shí),我們強(qiáng)烈建議您使用 OAuth 2.0 庫。使用他人經(jīng)過良好除錯(cuò)的代碼是一項(xiàng)最佳實(shí)踐,這樣做能有助于保護(hù)您自己和您的用戶。更多信息請(qǐng)參閱客戶端庫。
所有應(yīng)用程序在通過 OAuth 2.0 訪問谷歌 API 時(shí)都遵循一個(gè)基本模式。抽象地說,你需要遵循下面四步:
1. 從谷歌開發(fā)者控制臺(tái)獲得 OAuth 2.0 憑證。
訪問谷歌開發(fā)者控制臺(tái)來獲得 OAuth 2.0 憑證,例如應(yīng)用程序和谷歌都知道的一個(gè)客戶端 ID 和客戶端 secret。數(shù)據(jù)集會(huì)根據(jù)你所建立的應(yīng)用程序類型而有所不同,舉例來說,一個(gè) JavaScript 應(yīng)用程序并不要求一個(gè) secret,但是一個(gè) Web 服務(wù)器應(yīng)用程序就會(huì)要求。
2. 從谷歌授權(quán)服務(wù)器獲得一個(gè)訪問密鑰。
在你的應(yīng)用程序可以通過谷歌 API 訪問私有數(shù)據(jù)之前,它必須獲得一個(gè)訪問令牌來許可你訪問那個(gè) API。一個(gè)單獨(dú)的訪問令牌可以為多個(gè) API 許可不同程度的訪問權(quán)限。一個(gè)叫做 scope
(域)的變量參數(shù)可用來控制一個(gè)訪問令牌所許可的控制資源集和操作集。在一個(gè)有訪問令牌的請(qǐng)求中,你的應(yīng)用程序可發(fā)送一個(gè)或多個(gè) scope
參數(shù)。
有多種方法可以發(fā)出這個(gè)請(qǐng)求,這些方法根據(jù)你所創(chuàng)建的應(yīng)用程序類型不同而有所不同。舉例來說,一個(gè) JavaScript 應(yīng)用程序可以通過瀏覽器重定向到谷歌要求訪問令牌,而安裝在一個(gè)沒有瀏覽器的設(shè)備上的應(yīng)用程序則會(huì)使用 web 服務(wù)請(qǐng)求。
一些請(qǐng)求會(huì)要求用戶登陸到他們的谷歌賬戶作為一個(gè)驗(yàn)證步驟。登陸之后,用戶會(huì)被詢問他們是否愿意許可你的應(yīng)用程序所要求的權(quán)限。這個(gè)過程叫做“用戶準(zhǔn)許”。
如果用戶批準(zhǔn)了請(qǐng)求,谷歌授權(quán)服務(wù)器會(huì)發(fā)送一個(gè)訪問令牌給您的應(yīng)用程序(或一個(gè)應(yīng)用程序可以使用的授權(quán)碼來獲得訪問令牌)。如果用戶沒有批準(zhǔn)請(qǐng)求,服務(wù)器會(huì)返回一個(gè)錯(cuò)誤信息。
通常來說漸進(jìn)地要求各種 scope 是一項(xiàng)最佳實(shí)踐,比起一次性要求所有權(quán)限,當(dāng)需要進(jìn)行這種訪問時(shí)才發(fā)出相應(yīng)的請(qǐng)求會(huì)更好。 舉例來說,一個(gè)想要支持購買功能的應(yīng)用程序不應(yīng)該在用戶點(diǎn)擊“購買”按鈕之前要求谷歌錢包訪問權(quán); 詳情參閱漸進(jìn)式授權(quán)。
3. 發(fā)送訪問令牌給一個(gè) API。
當(dāng)一個(gè)應(yīng)用程序獲取訪問令牌時(shí),會(huì)在一個(gè) HTTP 授權(quán)頭里嵌入令牌發(fā)送給谷歌 API。當(dāng)然,以 URI 查詢串參數(shù)來發(fā)送令牌也是可行的,但我們不推薦這樣做,因?yàn)?URI 參數(shù)會(huì)在 log 中留下痕跡,而 log 本身并不是十分安全。同時(shí),避免創(chuàng)建不必要的 URI 參數(shù)名是一項(xiàng) REST 良好實(shí)踐。
訪問令牌僅對(duì)令牌所請(qǐng)求的 scope
中有描述的操作集和資源集有效。舉例來說,如果一個(gè)用于 Google+ API 的訪問令牌被分發(fā)下來,這個(gè)令牌并不能許可您訪問谷歌通訊錄 API。然而,你可以,將那個(gè)訪問令牌多次發(fā)送給 Google+ API 來實(shí)現(xiàn)相似操作。Web
4. 刷新訪問令牌,如果必要的話。
訪問令牌的生命期是有限的。如果你的應(yīng)用程序需要比一個(gè)訪問令牌的生命期更長(zhǎng)的時(shí)間來訪問谷歌 API,可以通過獲得一個(gè)刷新令牌(refresh token)來實(shí)現(xiàn)。刷新令牌可以讓您的應(yīng)用程序獲得新的訪問令牌。
注意: 將刷新令牌保存在一個(gè)安全的長(zhǎng)期存儲(chǔ)器內(nèi)并持續(xù)地使用他們直到令牌過期。每對(duì)客戶端-用戶(client-user)能獲得的刷新令牌的數(shù)量是有限的,同一個(gè)用戶在多個(gè)客戶端上能獲得的刷新令牌也是有限的,而且這些限制都不一樣。如果你的應(yīng)用程序請(qǐng)求的刷新令牌數(shù)量超過上述的任何一個(gè)限制,限制外較舊的刷新令牌會(huì)自動(dòng)失效。
谷歌 OAuth 2.0 端點(diǎn)支持使用下列語言和框架編寫的 Web 服務(wù)器應(yīng)用程序:PHP,Java,Python,Ruby,和 ASP.NET。
授權(quán)程序會(huì)在您的應(yīng)用程序?qū)g覽器重定向到谷歌 URL 時(shí)啟動(dòng); URL 包含了查詢參數(shù)來指出請(qǐng)求的訪問類型。谷歌負(fù)責(zé)用戶驗(yàn)證,會(huì)話選擇,和用戶準(zhǔn)許。這一程序的結(jié)果是授權(quán)碼,應(yīng)用程序可以通過這個(gè)碼來獲得一個(gè)訪問令牌和一個(gè)刷新令牌。
應(yīng)用程序應(yīng)存儲(chǔ)刷新令牌供未來使用,并使用訪問令牌來訪問谷歌 API。一旦訪問令牌過期,應(yīng)用程序可使用刷新令牌來獲得新的訪問令牌。
http://wiki.jikexueyuan.com/project/google-oauth-2/images/webflow.png" alt="" />
詳情請(qǐng)參閱使用 OAuth 2.0 for Web 服務(wù)器應(yīng)用程序。
谷歌 OAuth 2.0 端點(diǎn)支持安裝在各種設(shè)備上的應(yīng)用程序,例如電腦、移動(dòng)設(shè)備、和平板。當(dāng)你通過谷歌開發(fā)者控制臺(tái)創(chuàng)建客戶端 ID 時(shí),聲明這是一個(gè)本地安裝的應(yīng)用程序,然后選擇根據(jù)你的應(yīng)用程序類別選擇 Android,Chrome,iOS,或其他。
這個(gè)過程的結(jié)果是一個(gè)客戶端 ID,在一些情況下,還會(huì)有一個(gè)客戶端 secret,你需要將其嵌入到你的應(yīng)用程序源代碼中。(在這個(gè)情況下,客戶端 secret 顯然沒被當(dāng)做秘密看待。)
授權(quán)程序會(huì)在您的應(yīng)用程序?qū)g覽器重定向到谷歌 URL 時(shí)啟動(dòng); URL 包含了查詢參數(shù)來指出請(qǐng)求的訪問類型。谷歌 負(fù)責(zé)用戶驗(yàn)證,會(huì)話選擇,和用戶準(zhǔn)許。這一程序的結(jié)果是授權(quán)碼,應(yīng)用程序可以通過這個(gè)碼來獲得一個(gè)訪問令牌和一個(gè)刷新令牌。
應(yīng)用程序應(yīng)存儲(chǔ)刷新令牌供未來使用,并使用訪問令牌來訪問谷歌 API。一旦訪問令牌過期,應(yīng)用程序可使用刷新令牌來獲得新的訪問令牌.
http://wiki.jikexueyuan.com/project/google-oauth-2/images/webflow.png" alt="" />
詳情請(qǐng)參閱使用 OAuth 2.0 for 本地安裝的應(yīng)用程序。
谷歌 OAuth 2.0 端點(diǎn)支持在瀏覽器里運(yùn)行的 JavaScript 應(yīng)用程序。
授權(quán)程序會(huì)在您的應(yīng)用程序?qū)g覽器重定向到谷歌 URL 時(shí)啟動(dòng); URL 包含了查詢參數(shù)來指出請(qǐng)求的訪問類型。谷歌 負(fù)責(zé)用戶驗(yàn)證,會(huì)話選擇,和用戶準(zhǔn)許。
這一程序的結(jié)果是訪問令牌,客戶端應(yīng)該先對(duì)令牌進(jìn)行驗(yàn)證再將其包含在谷歌 API 請(qǐng)求內(nèi)。一旦令牌過期,應(yīng)用程序可重復(fù)同一步驟。
http://wiki.jikexueyuan.com/project/google-oauth-2/images/tokenflow.png" alt="" />
詳情請(qǐng)參閱使用 OAuth 2.0 for 客戶端方面應(yīng)用程序.
谷歌 OAuth 2.0 端點(diǎn)支持在輸入有限的設(shè)備上運(yùn)行的應(yīng)用程序,例如家用游戲機(jī)、攝影機(jī)、打印機(jī)等。
授權(quán)程序會(huì)在您的應(yīng)用程序通過向谷歌 URL 發(fā)送 Web 服務(wù)請(qǐng)求來獲取授權(quán)碼時(shí)啟動(dòng);服務(wù)器回應(yīng)包含多個(gè)參數(shù),包括了一個(gè) URL 和一個(gè)代碼讓應(yīng)用程序來顯示給用戶。
用戶從設(shè)備獲得 URL 和代碼后,應(yīng)切換到另一個(gè)擁有更強(qiáng)大輸入功能的設(shè)備或者電腦,然后啟動(dòng)瀏覽器,訪問獲得的 URL 并登陸,然后輸入獲得的代碼。
與此同時(shí),應(yīng)用程序會(huì)定期輪詢谷歌 URL。若用戶同意訪問,谷歌服務(wù)器便會(huì)發(fā)回包含一個(gè)訪問令牌和刷新令牌的回應(yīng)。應(yīng)用程序應(yīng)存儲(chǔ)刷新令牌供未來使用,并使用訪問令牌來訪問谷歌 API。一旦訪問令牌過期,應(yīng)用程序可使用刷新令牌來獲得新的訪問令牌.
http://wiki.jikexueyuan.com/project/google-oauth-2/images/deviceflow.png" alt="" />
詳情請(qǐng)參閱使用 OAuth 2.0 for 設(shè)備。
谷歌 API 中例如預(yù)測(cè) API 和谷歌云存儲(chǔ)可以在您不訪問用戶信息的情形下代您的應(yīng)用程序?qū)崿F(xiàn)相關(guān)功能。在這種情況下你的應(yīng)用程序需要向 API 證明自己的身份,不過這樣做不需要用戶準(zhǔn)許。相似地,在企業(yè)應(yīng)用中,你的應(yīng)用程序可以要求代理來訪問一些資源。
要實(shí)現(xiàn)這些服務(wù)器與服務(wù)器之間的互動(dòng),你需要一個(gè)服務(wù)賬戶,該賬戶是屬于你的應(yīng)用程序的而不是最終用戶個(gè)體。你的應(yīng)用程序以服務(wù)賬戶名義來調(diào)用谷歌 API,這種情形下也不需要用戶準(zhǔn)許。(如果不使用服務(wù)賬戶,而讓應(yīng)用程序以最終用戶的名義來調(diào)用谷歌 API,則在一些情況下會(huì)要求用戶準(zhǔn)許。)
注意: 這些服務(wù)賬戶方案要求應(yīng)用程序自行創(chuàng)建 JSON Web 令牌(JWTs)并且自己進(jìn)行密碼學(xué)簽名。我們強(qiáng)烈建議您使用庫來完成這些工作。如果您不使用抽象化令牌創(chuàng)建和簽名的庫,自己編寫這部分代碼的話,則有犯錯(cuò)誤的風(fēng)險(xiǎn),這些錯(cuò)誤可能會(huì)對(duì)您的應(yīng)用程序的安全照成嚴(yán)重沖擊。若想了解這種方案所需的庫的列表,請(qǐng)參閱關(guān)于服務(wù)賬戶的文檔。
從谷歌開發(fā)者控制臺(tái)獲得的一個(gè)服務(wù)賬戶的憑證,包括了一個(gè)自動(dòng)生成的唯一的電子郵箱地址、一個(gè)客戶端 ID,和至少一對(duì)公鑰和私鑰。使用客戶端 ID 和一個(gè)私鑰來創(chuàng)建一個(gè)經(jīng)過簽名的 JWT 并以正確的格式構(gòu)造一個(gè)訪問令牌請(qǐng)求。然后應(yīng)用程序?qū)⒘钆普?qǐng)求發(fā)送給谷歌 OAuth 2.0 授權(quán)服務(wù)器,并獲得訪問令牌。然后應(yīng)用程序使用訪問令牌來訪問谷歌 API。當(dāng)訪問令牌過期,應(yīng)用程序重復(fù)這個(gè)步驟來獲得新令牌。
http://wiki.jikexueyuan.com/project/google-oauth-2/images/serviceaccount.png" alt="" />
詳情請(qǐng)參閱關(guān)于服務(wù)賬戶的文檔。
您的代碼應(yīng)該要能預(yù)料一個(gè)頒發(fā)下來的令牌有失效的可能性。下面幾種原因都能導(dǎo)致令牌失效:
目前每個(gè)谷歌用戶賬戶都有令牌的數(shù)量限制,最多 25 個(gè)。如果一個(gè)用戶擁有 25 個(gè)有效令牌,則下一個(gè)驗(yàn)證請(qǐng)求成功時(shí),會(huì)在沒有任何用戶可見的警告的情況下廢除最后一次使用時(shí)間最老的令牌。
如果你需要許可多個(gè)程序、機(jī)器、或設(shè)備,其中一個(gè)解決方法就是限制你許可給單個(gè)用戶的客戶端數(shù)量在 15 或 20 內(nèi)。如果你是谷歌 Apps 管理員,你可以創(chuàng)建額外的管理員用戶并使用他們來授權(quán)一些客戶端。
下面的客戶端庫整合了一些流行的框架,讓您更簡(jiǎn)單地應(yīng)用 OAuth 2.0。隨著時(shí)間的推移,會(huì)有更多的新功能添加到這些庫中。