搭配 Google Data API 使用 OAuth

Google Data API 團隊 Eric Bidelman
2008 年 9 月

簡介

對開發人員來說,這真是太棒了!我們開始看到許多網路標準採用於網路,Google 一直以來都擁有龐大的標準和培養開放原始碼社群。

最近,所有 Google Data API 都支援 OAuth,這是一種開放式通訊協定,旨在標準化電腦版和網路應用程式存取使用者私人資料的方式。OAuth 可讓您以標準安全的方式執行 API 驗證。身為程式設計師,我們教導了盡可能重複使用程式碼。OAuth 可協助開發人員減少編寫的重複程式碼數量,並更輕鬆地建立適用於多種不同服務供應商的多項服務的工具。

目標對象

本文假設您已熟悉一或多個 Google Data API,但不一定是 OAuth 背後的概念。如果您才剛開始使用 Chrome,或只是想要瞭解 OAuth,請再接再厲。本文將提供概念的基礎。我也會討論 Google OAuth 的實作詳細資訊。

本文的適用對象為熟悉 AuthSub 的開發人員,特別是已註冊進階安全性模式的開發人員。 在此同時,我會盡量凸顯這兩種通訊協定的相似度差異。如果您的應用程式使用 AuthSub,您可以利用此資訊來遷移至 OAuth,這是一個新的開放式通訊協定。


有點術語

瞭解 OAuth 的重點在於理解其術語。 OAuth 規格和 Google 的網路應用程式 OAuth 驗證說明文件非常依賴特定定義,因此讓我們能詳細瞭解 Google 的 OAuth 實作方式。

  1. 「OAuth 舞蹈」

    我用於說明完整的 OAuth 驗證/授權程序的非官方用語。

  2. (OAuth) 要求憑證

    這個初始符記可讓 Google 瞭解您的應用程式要求存取其中一個 Google Data API。OAuth 舞的第二個步驟是讓使用者手動授予資料的存取權。如果這個步驟成功,要求權杖就會獲得授權。

  3. (OAuth) 存取憑證

    最後一步是將授權要求憑證轉換為存取憑證。應用程式取得這個憑證後,除非撤銷憑證,否則使用者不必再次執行 OAuth 舞蹈。

    與 AuthSub 相似:
    OAuth 存取憑證與安全 AuthSub 工作階段憑證相同。

  4. (OAuth) 端點

    這些是驗證應用程式並取得存取權杖所需的 URI。共有三個步驟,每個步驟都是 OAuth 程序的每個步驟。 Google 的 OAuth 端點如下:

    取得要求憑證:https://www.google.com/accounts/OAuthGetRequestToken
    授權要求憑證:https://www.google.com/accounts/OAuthAuthorizeToken
    升級為存取憑證:https://www.google.com/accounts/OAuthGetAccessToken

    與 AuthSub 相似:
    變更存取權杖的授權要求權杖與將一次性使用 AuthSub 憑證分別升級至 https://www.google.com/accounts/AuthSubRequestTokenhttps://www.google.com/accounts/AuthSubSessionToken 的長效工作階段符記相似。差別在於 AuthSub 沒有初始要求憑證的概念。而是從 AuthSubRequestToken 授權頁面啟動憑證程序。

  5. (OAuth) 服務供應商

    在 Google Data API 中,該供應商為 Google。服務供應商通常會用來提供提供 OAuth 端點的網站或網站服務。 OAuth 服務供應商的另一個例子是 MySpace。

  6. (OAuth) 消費者

    要求存取使用者資料 (即您的應用程式) 的程式。OAuth 通訊協定有彈性,因為它支援多種不同類型的用戶端 (網頁、已安裝、桌上型電腦、行動裝置)。

注意:雖然 OAuth 通訊協定支援桌面版/安裝版應用程式,但 Google 僅支援網路應用程式的 OAuth。

開始使用

註冊

您必須進行一些設定,才能開始透過 Google Data API 使用 OAuth。由於「所有」OAuth 要求都必須進行數位簽署,因此您必須先註冊網域,然後將公開憑證上傳到 Google。如要進一步瞭解相關做法,請參閱網頁式應用程式的註冊產生已註冊註冊模式的金鑰和憑證一節。

簽署要求

當您註冊網域後,就可以開始簽署要求。OAuth 的最棘手概念之一,就是如何正確建構 oauth_signature 以及簽名基礎字串的概念。基礎字串是您使用私密金鑰 (使用 RSA_SHA1) 簽署的資料。結果是您為 oauth_signature 設定的值。

要求範例

GET 使用者在 http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 擁有的 Google 日曆清單

基本字串格式 base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters
基本字串範例 GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime
HTTP 要求範例
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

注意:這僅供參考,您的oauth_signature將大幅增加。

基本字串的注意事項:

  • orderby=starttime 查詢參數會和提出其他的 oauth_* 參數,並按字母順序值排序。
  • 此字串包含「?」字元。
  • base-http-request-url 部分僅包含經過網址編碼的基礎網址:http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull
  • oauth_token 採用雙重網址編碼。

Authorization」標頭的附註:

  • oauth_* 參數的排序在 Authorization 標頭中並沒有影響。
  • 標頭中的 orderby=starttime 不會與基礎字串一樣。這個查詢參數會成為請求網址的一部分。

如要進一步瞭解如何使用 OAuth 簽署要求,請參閱簽署 OAuth 要求

與 AuthSub 的差異:
以下舉例說明使用安全 AuthSub 的相同範例:

基本字串格式 base_string = http-method http-request-URL timestamp nonce
基本字串範例
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
HTTP 要求範例
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

如要進一步瞭解如何使用 AuthSub 簽署要求,請參閱簽署 AuthSub 要求

OAuth Playground 工具

目的

部分使用者建議 OAuth 有很大的學習曲線。相較於 Google 的其他驗證 API,我同意。當您擴充應用程式以使用其他 (非 Google 服務) 服務時,OAuth 的優勢會顯而易見。您只要編寫一段適用於不同服務供應商及其 API 的驗證碼,就很適合使用。 我們稍後會說明您如何學習通訊協定。

我建立的是 OAuth Playground 工具,可協助開發人員破解 OAuth 設定。 您可以使用 Playground 協助偵錯、檢查自己的實作項目,或利用 Google Data API 進行實驗。

這個選項的功能

  1. 說明 OAuth 驗證流程:擷取要求憑證、授權憑證,並將其升級為存取權杖。
  2. 顯示每個要求的正確簽名基本字串。
  3. 顯示每個要求的正確 Authorization 標頭。
  4. 示範如何使用 oauth_token 與通過驗證的 Google 資料動態饋給互動。 您可以GET/POST/PUT/DELETE 資料。
  5. 直接在瀏覽器中查看已驗證的資訊提供。
  6. 可讓您測試自己的 oauth_consumer_key (已註冊網域) 和私密金鑰。
  7. 瞭解您的oauth_token可用的 Google 資料動態饋給服務。

示範執行

步驟 1:選擇範圍

首先,請選擇一或多個範圍,決定要使用的 API。在這個示範中,我申請的是可和 Blogger Google 聯絡人搭配使用的權杖。

與 AuthSub 相似:
AuthSub 也需要 scope 參數來控制權杖可存取的資料範圍。Google 已按照 OAuth 規格的建議,實作這個參數。

步驟 2:修改 OAuth 參數和設定

目前,請勿修改 [修改 OAuth 參數] 方塊中的任何設定。之後,您只要將 oauth_consumer_key 變更為已註冊的網域,然後按一下 [使用自己的私密金鑰],即可用您的私密金鑰進行測試。您只能使用 TEST 私密金鑰。

注意oauth_signature_methodoauth_consumer_key 是唯一可以在此編輯的欄位。系統會自動為你產生 oauth_timestampoauth_nonceoauth_token

除了 RSA-SHA1 以外,您還可以選擇將 oauth_signature_method 用於 HMAC-SHA1。在這種情況下,Playground 會顯示額外的方塊,您必須在其中輸入自己的 oauth_consumer_key 和用戶端密鑰。您可以在註冊網域的 https://www.google.com/accounts/ManageDomains 頁面找到這些值。

與 AuthSub 的差異:
在安全 AuthSub 中,沒有可明確設定網域名稱的參數。網域會納入 next 網址參數中。OAuth 中有以下參數:oauth_consumer_key。將網域設為已註冊網域。

步驟 3-5:取得存取憑證

取得 OAuth 存取憑證需要三個步驟。第一步是擷取要求憑證。讓 Google 知道您的應用程式正在啟動 OAuth 舞蹈。

首先,按一下 [取得憑證] 方塊中的 [要求憑證] 按鈕。

某些欄位會填入資料。

  • 「簽名基本字串」會顯示用於建立 oauth_signature 參數的基礎字串的正確格式。
  • 「Authorization 標頭」會顯示與要求對應的 Authorization 標頭。
  • 「修改 OAuth 參數」方塊會填入要求中傳送的 oauth_nonceoauth_timestamp 值。
  • oauth_token 輸入內容中會填入回應主體傳回的對應值。Playground 也會顯示目前提供的 oauth_token 類型。目前這是要求憑證。

接下來,按一下 [取得憑證] 方塊中的 [授權] 按鈕。

在這個授權頁面上,按一下 [授予存取權] 按鈕以授權要求權杖,並重新導向至 OAuth Playground。

與 AuthSub 相似:
這個授權頁面與 AuthSub 相同。

與 AuthSub 的差異:
AuthSub 的 next 網址參數與 oauth_callback 參數相似。差別在於在 OAuth 中,oauth_callback 為選用項目。使用者按一下 [授予存取權] 按鈕後,要求憑證就會獲得授權,而憑證也可以升級至 https://www.google.com/accounts/OAuthGetAccessToken

提示:如果您要編寫網路應用程式,建議指定 oauth_callback 網址,因為這樣可以提供更優質的使用者體驗。

最後,按一下 [取得憑證] 方塊中的 [存取憑證] 按鈕。

這個動作會升級授權要求憑證 (如紅色的「存取權杖」標籤所示)。

如果您想要擷取新權杖,請按一下 [重新開始] 以重新執行 OAuth 舞蹈。

現在我們可以做點有趣的事情了!

使用存取權杖

您現在可以查詢、插入、更新或刪除資料了。使用實際資料時,請務必執行最後三種 HTTP 方法!

提示:如要尋找可存取的存取憑證,請按一下 [可用的動態消息] 按鈕。

以下是查詢範例:GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

這個範例最多只能傳回 3 個特定網誌上的文章。您也可以直接在瀏覽器中查看傳回的動態饋給/項目,方法是按一下語法醒目顯示區域下方的 [在瀏覽器中查看] 連結。

範例:如何更新訊息

  1. 找出你要更新文章的 rel="edit",然後找出含有 <link> 的元素。如下所示:
    <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

    在「輸入 Google 資料動態饋給」輸入內容中貼上 href 網址。

  2. 按一下語法醒目顯示面板頂端的 [檢視純文字],複製現有項目的 XML。只複製回應內文,不要複製標頭。
  3. 將 HTTP 方法下拉式選單變更為 PUT
  4. 點選下拉式選單下方的 [輸入訊息資料],然後將 <entry> XML 貼到彈出式視窗中。
  5. 按一下 [執行] 按鈕。

伺服器會傳回 200 OK

提示:請不要手動複製 edit 連結,而是取消勾選 [語法醒目顯示方式] 核取方塊。查詢完畢之後,您只要按一下 XML 回應主體中的連結即可。

結語

AtomPub/Atom 發布通訊協定 (Google Data API 的基本通訊協定) 和 OAuth 等技術有助於推動網路向前發展。隨著越來越多網站開始採用這些標準,開發人員也會成為贏家。要尋找殺手級應用程式,幾乎不容易下手。

如果您對 OAuth Playground 有任何疑問或意見,或者可以使用 OAuth 搭配 Google API,請造訪 G Suite API 和 Marketplace API 支援論壇

資源