Google Data 通訊協定中的驗證和授權

警告：本頁面說明 Google 的舊版 API (即 Google Data API)；該 API 只與 Google Data API 目錄中列出的 API 相關，其中許多 API 已由新版 API 取代。如需特定新的 API 的相關資訊，請參閱新 API 的說明文件。如要瞭解如何使用新版 API 授權要求，請參閱 Google 帳戶驗證與授權。

第三方應用程式通常需要特定類型的 Google 帳戶，才能存取特定類型的活動。為了確保使用者資料不會遭到濫用，所有存取要求都必須獲得帳戶持有人的核准。存取權控管分為兩種元件：驗證和授權。

驗證服務可讓使用者使用 Google 帳戶登入您的應用程式。

授權服務可讓使用者透過應用程式存取儲存在 Google 應用程式中的資料。Google 非常重視隱私權，凡是需要存取使用者資料的應用程式都必須獲得使用者的授權。

驗證和授權服務通常統稱為「驗證」。

Google API 的驗證和授權可讓第三方應用程式僅針對特定類型的活動，限制使用者存取 Google 帳戶的權限。本文件會介紹可用的驗證機制，並說明各種機制可以為您的應用程式提供哪些功能。

• Google 登入讓使用者透過 Google 憑證登入網站，簡單又方便。其中包含能輕鬆整合不同裝置的一組工具。
• OAuth 2.0 是所有 Google API 的授權通訊協定，OAuth 2.0 需要安全資料傳輸層 (SSL) 的安全性，因此不需要求應用程式直接執行加密編譯簽署。應用程式可利用這項通訊協定，要求存取使用者 Google 帳戶相關資料。
• 使用 OAuth 2.0 登入 (OpenID Connect) 可讓使用者登入自己的 Google 帳戶，藉此驗證他們的身分。這是 OpenID 的替代選項，OpenID 使用者應計劃改用 OAuth 2.0 登入。

如果您的應用程式是小工具 (可在 iGoogle 或其他 OpenSocial 容器中使用)，請參閱「小工具驗證」一節。

注意：本文旨在提供每種驗證方法的總覽。如需每種方法的詳細資訊，請參閱完整的 Google Account Authentication API 說明文件。

另請參閱 Google Accounts API 群組，瞭解如何使用 Google Accounts API。

OAuth - 網頁和已安裝應用程式的授權

許多 Google 服務允許第三方存取使用者產生的資料，例如日曆或文件資料，前提是必須獲得使用者授權。這項功能可讓使用者在 Google 應用程式和第三方應用程式之間共用及交換資料，以各種用途。

Google 支援兩種版本的 OAuth，可用來取得使用者的 Google 資料存取權：OAuth 1.0 和 OAuth 2.0，兩者皆提供網頁應用程式和已安裝應用程式的存取權。

網頁和已安裝的 OAuth 2.0

網頁應用程式或已安裝的應用程式可以使用經過簡化的新版 OAuth 2.0 通訊協定，授權存取與 Google 帳戶相關聯的資料。有關如何導入 Google 的 OAuth 2.0 詳細資訊及範例，請參閱 OAuth 2.0 文件。

網路應用程式適用的 OAuth 1.0

如果網路應用程式需要授權，才能存取與 Google 帳戶或 Google Apps 帳戶相關聯的資料，則可使用 Google 的 OAuth API 實作。如需網頁式應用程式 OAuth 實作的完整資訊 (包括範例)，請參閱 Web OAuth 專用的網路應用程式指南，或參閱本文件的總覽。

已安裝應用程式的 OAuth 1.0

在使用者電腦和行動裝置上安裝的應用程式可以使用 OAuth，來授權存取與 Google 帳戶相關聯的資料。如需為已安裝的應用程式實作 OAuth 的完整資訊，請參閱已安裝應用程式適用的 OAuth 指南，或參閱本文件的總覽。

將 OAuth 與網路應用程式搭配使用

所有 Google Data API 均支援 OAuth，這項公開標準可用來授權在網路應用程式中使用資料。凡是發出 OAuth 要求的網路應用程式，都必須上傳安全性憑證，並且向 Google 註冊。如需詳細資訊，請參閱註冊網路應用程式的網路應用程式。

Google Data API 用戶端程式庫提供許多方法，可協助您在網路應用程式中使用 OAuth。具體來說，有一種方法可以建構要求憑證、授權要求憑證，以及為授權憑證交換授權要求憑證。資料庫向 Google Data 服務提出要求時，也會處理必要的簽署演算法。如需搭配 Google Data API 用戶端程式庫使用 OAuth 的詳細範例，請參閱搭配 Google Data API 用戶端程式庫使用 OAuth 一文。

OAuth 授權程序

OAuth 授權程序包括您的網路應用程式、Google 的授權伺服器和使用者之間的一系列互動。

基本程序如下：

1. 您的應用程式會要求存取，並從 Google 的授權伺服器取得未經授權的要求憑證。
2. Google 會要求使用者授予必要的資料存取權。
3. 應用程式會從授權伺服器取得已授權的要求憑證。
4. 您針對存取權杖交換授權要求憑證。
5. 您可以使用存取憑證，向 Google 的服務存取伺服器要求提供資料。

當應用程式最初要求存取使用者的資料時，Google 就會為您的應用程式發出未經授權的要求憑證。

如果使用者尚未登入，Google 會提示使用者登入。接著，Google 會顯示授權頁面，讓使用者查看應用程式要求存取哪些 Google 服務資料。

如果使用者核准您應用程式的存取要求，Google 就會發出授權要求憑證。每個要求憑證的有效期限為一小時。只有獲得授權的要求權杖才能交換成存取權杖，而且每個授權請求憑證只能執行一次。

根據預設，存取憑證已持續存在。每個存取權杖都是在原先的授權要求中指定的使用者帳戶，並且只授予該請求中指定的服務。您的應用程式應該妥善儲存存取權杖，因為存取使用者資料時一律需要用到。

為 OAuth 做好準備

您必須先完成下列工作，才能將應用程式設為搭配 Google 授權服務使用 OAuth。

決定是否要註冊網頁應用程式

如要讓使用者進一步保護自己的資料安全，可以選擇向 Google 註冊您的網頁應用程式，並使用已註冊的安全性憑證簽署要求。部分 Google Data API 動態饋給僅適用於已註冊的應用程式。請查看您所需使用的 Google Data API 說明文件，確認該 API 是否僅適用於已註冊的應用程式。

應用程式必須簽署您提出的每個 OAuth 要求。如果您選擇使用 RSA-SHA1 簽名來簽署要求，則必須在註冊過程中上傳安全性憑證。

或者，您也可以使用 HMAC-SHA1 簽名來簽署要求。HMAC-SHA1 簽名不需要憑證。而是在您產生註冊資訊之後，Google 會產生 OAuth consumer secret 值，並顯示在您網域的註冊頁面上。

如要進一步瞭解註冊程序，請參閱註冊網路應用程式一文。

決定應用程式要存取的資料範圍

每項 Google 服務都會設定透過 Google Data API 的存取限制。此存取權以範圍值表示。某些服務提供多種範圍值，可讓使用者選擇要讓哪些應用程式存取哪些資料。如要瞭解您要存取的 Google 服務可用範圍值，請參閱該服務的說明文件。

一般而言，您應該針對包含所需資料的最小範圍要求憑證。例如，如果應用程式需要存取使用者的「所有日曆」資訊提供，則應要求 http://www.google.com/calendar/feeds/default/allcalendars/full 範圍的一個憑證。

設定 OAuth 憑證的管理機制

取得使用者資料的 OAuth 存取憑證時，您必須代表該存取憑證，以代表使用者日後與指定 Google 服務之間的互動。

您的應用程式應以安全的方式管理憑證儲存空間，包括追蹤每個憑證的有效 Google 服務。如果您需要多項 Google 服務的存取權，可以取得多個存取憑證，但每位使用者及應用程式隨時都可以擁有最多十個存取憑證。

如果您的應用程式支援多個使用者帳戶，您必須追蹤每個憑證相關聯的帳戶。 每個 OAuth 憑證都是分別針對獲得授權的使用者提供。您的應用程式必須能夠將憑證與正確的使用者建立關聯。其中一種方式就是先發出 Cookie 給使用者，再提出憑證要求。使用者授予要求的資料存取權後，Google 會傳送授權要求憑證，並將使用者重新導向至您的應用程式。然後使用應用程式的 Cookie，將憑證與正確的使用者建立關聯。

設定存取 Google 服務機制的機制

每個 Google 服務請求都必須經過簽署，且必須包含有效的 OAuth 存取憑證。一般來說，每項要求都是以 HTTP GET 要求的形式傳送，標頭中會包含存取憑證和簽名。寫入新資料的要求應使用 HTTP POST。

如要進一步瞭解每個 Google Data API 的正確要求格式，請參閱該 API 的說明文件。

實作 OpenID (選擇性)

如果您正在實作 OpenID 以進行使用者驗證，請考慮使用混合通訊協定來合併這兩種程序。如果使用 OpenID+OAuth，取得要求憑證並進行授權的工作會以 OpenID 擴充功能的 OpenID 要求來處理。與 OAuthGetRequestToken 相同，這些擴充功能可用來識別要存取的 Google 服務。成功回應 OpenID 要求時會包含已授權的要求憑證。收到這個憑證後，請使用 OAuthGetAccessToken 以交換這個存取憑證。

使用 OAuth 憑證

如要使用 OAuth，您的應用程式必須產生格式正確的已簽署憑證要求呼叫，並依照下列順序處理回應：

1. 取得未經授權的要求憑證 (OAuthGetRequestToken)
2. 授權要求憑證 (OAuthAuthorizeToken)
3. 將授權要求憑證轉換為存取權杖 (OAuthGetAccessToken)

無論應用程式是否已註冊，所有的 OAuth 要求都必須經過簽署。詳情請參閱簽署 OAuth 要求。

您可以在 OAuth Playground 中嘗試要求及接收授權憑證。

如需詳細的說明文件，請參閱 OAuth API 參考資料。

設定回呼網址

您可以在 OAuthGetRequestToken 要求中指定 oauth_callback 的值，藉此判斷 Google 會在使用者授權存取要求後，將使用者重新導向。回呼網址可以包含查詢參數。重新導向將會包含相同的查詢參數，以及應用程式必須能夠剖析的授權要求權杖。

例如，當支援多種語言時，您可以加入查詢參數，以識別使用者正在查看的應用程式版本。「http://www.yoursite.com/Retrievetoken?Lang=de」的 oauth_callback 值會導致重新導向「http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE」。剖析符記和語言參數可確保使用者能重新導向到正確的網站版本。

如未提供 oauth_callback 參數，Google 會在授權存取要求後，將使用者導向至顯示驗證碼 (查看範例) 的網頁。使用者必須手動返回您的應用程式並輸入驗證編號，才能取得授權的要求憑證。

辨識您的應用程式

使用者要求存取權時，Google 通常會顯示應用程式名稱 (查看範例)。

如果您的應用程式尚未註冊，請在 OAuthGetRequestToken 要求中使用 xoauth_displayname 參數來指定應用程式名稱。如未指定該參數，Google 會顯示 oauth_callback 參數提供的網址網域名稱。如未提供回呼網址，Google 會顯示「匿名」字串。

如果您的應用程式已經註冊，請不要設定這個參數。根據預設，Google 會顯示註冊過程中指定的顯示名稱。如果您在 OAuthGetRequestToken 要求中設定了顯示名稱，Google 會使用這個名稱來取代您註冊的顯示名稱，而且會隨附一則訊息，指出無法驗證應用程式的身分。

注意：如要在 OAuth Playground 中設定 xoauth_displayname 參數，請先勾選 [進階] 方塊，再擷取要求憑證。

使用 Google Apps 網域

如果您的應用程式是專為代管 Google 帳戶網域的使用者所設計，建議您在授權憑證時使用 hd 參數。如要進一步瞭解 hd 參數，請參閱處理擁有多個帳戶的使用者一文。

進一步瞭解 OAuth

若要進一步瞭解 Google 的 OAuth 導入方式，包括如何註冊應用程式及建立必要的 OAuth 參數，請參閱以下其他資源：

• 使用 OAuth 搭配 Google Data API 用戶端程式庫
• 文章：將 OAuth 與 Google Data API 搭配使用，包括 OAuth Playground 說明。這項互動工具可用於試用 OAuth。
• 網路應用程式適用的 OAuth (完整說明文件)
• 網頁式應用程式的註冊
• 產生金鑰和憑證
• OAuth 規格

返回頁首

使用 OAuth 搭配已安裝的應用程式

所有 Google Data API 都支援 OAuth，這是一個開放授權，可授權應用程式使用資料。已安裝的應用程式無須向 Google 註冊，才能使用 OAuth。

OAuth 授權程序

OAuth 授權程序包含應用程式、Google 授權伺服器和使用者之間的一系列互動。

基本程序如下：

1. 您的應用程式會要求存取，並從 Google 的授權伺服器取得未經授權的要求憑證。
2. Google 會要求使用者授予必要的資料存取權。
3. 應用程式會從授權伺服器取得已授權的要求憑證。
4. 您針對存取權杖交換授權要求憑證。
5. 您可以使用存取憑證，向 Google 的服務存取伺服器要求提供資料。

當應用程式最初要求存取使用者的資料時，Google 就會為您的應用程式發出未經授權的要求憑證。

如果使用者尚未登入，Google 會提示使用者登入。接著，Google 會顯示授權頁面，讓使用者查看應用程式要求存取哪些 Google 服務資料。

如果使用者核准您應用程式的存取要求，Google 就會發出授權要求憑證。每個要求憑證的有效期限為一小時。只有獲得授權的要求權杖才能交換成存取權杖，而且每個授權請求憑證只能執行一次。

OAuth 支援使用未註冊模式的安裝版應用程式。取得授權要求憑證的方法有很多種，即使應用程式安裝的裝置沒有網路瀏覽器，也可以使用 OAuth 授權應用程式。

根據預設，存取憑證已持續存在。每個存取權杖都是在原先的授權要求中指定的使用者帳戶，並且只授予該請求中指定的服務。您的應用程式應該妥善儲存存取權杖，因為存取使用者資料時一律需要用到。

為 OAuth 做好準備

您必須先完成下列工作，才能將應用程式設為搭配 Google 授權服務使用 OAuth。

決定應用程式要存取的資料範圍

每項 Google 服務都會設定透過 Google Data API 的存取限制。此存取權以範圍值表示。某些服務提供多種範圍值，可讓使用者選擇要讓哪些應用程式存取哪些資料。如要瞭解您要存取的 Google 服務可用範圍值，請參閱該服務的說明文件。

一般而言，您應該針對包含所需資料的最小範圍要求憑證。例如，如果應用程式需要存取使用者的「所有日曆」資訊提供，則應要求 http://www.google.com/calendar/feeds/default/allcalendars/full 範圍的一個憑證。

設定 OAuth 憑證的管理機制

取得使用者資料的 OAuth 存取憑證時，您必須代表該存取憑證，以代表使用者日後與指定 Google 服務之間的互動。

您的應用程式應以安全的方式管理憑證儲存空間，包括追蹤每個憑證的有效 Google 服務。

如果您的應用程式支援多個使用者帳戶，您必須追蹤每個憑證相關聯的帳戶。

設定存取 Google 服務機制的機制

每個 Google 服務請求都必須經過簽署，且必須包含有效的 OAuth 存取憑證。一般來說，每項要求都是以 HTTP GET 要求的形式傳送，標頭中會包含存取憑證和簽名。寫入新資料的要求應使用 HTTP POST。

如要進一步瞭解每個 Google Data API 的正確要求格式，請參閱該 API 的說明文件。

使用 OAuth 憑證

如要使用 OAuth，您的應用程式必須產生格式正確的已簽署憑證要求呼叫，並依照下列順序處理回應：

1. 取得未經授權的要求憑證 (OAuthGetRequestToken)
2. 授權要求憑證 (OAuthAuthorizeToken)
3. 將授權要求憑證轉換為存取權杖 (OAuthGetAccessToken)

無論應用程式是否已註冊，所有的 OAuth 要求都必須經過簽署。詳情請參閱簽署 OAuth 要求。已安裝的應用程式應按照未註冊應用程式的說明操作。

您可以在 OAuth Playground 中嘗試要求及接收授權憑證。

如需詳細的說明文件，請參閱 OAuth API 參考資料。

辨識您的應用程式

使用者要求存取權時，Google 通常會顯示應用程式名稱 (查看範例)。

在 OAuthGetRequestToken 要求中使用 xoauth_displayname 參數來指定您的應用程式名稱。如未指定該參數，Google 會顯示 oauth_callback 參數提供的網址網域名稱。如未提供回呼網址，Google 會顯示「匿名」字串。

注意：如要在 OAuth Playground 中設定 xoauth_displayname 參數，請先勾選 [進階] 方塊，再擷取要求憑證。

啟動網路瀏覽器

在 OAuth 授權流程中，您的應用程式必須發出 OAuthAuthorizeToken 要求。使用者必須登入 Google 網頁，並授權應用程式存取要求。

• 大部分的應用程式都應使用 AutoDetect 模式
• 如果應用程式無法啟動完整網路瀏覽器，請使用裝置模式。
• 開發模式只應在早期開發期間使用。

自動偵測模式

如果可以的話，您的應用程式應開啟瀏覽器視窗，並發出 OAuthAuthorizeToken 要求以開啟 Google 網頁。Google 傳回授權的權杖時，應用程式應偵測該憑證，並從網路瀏覽器中找回焦點。

此模式會要求您提供回呼網址，當使用者授權存取要求後，系統會將他們重新導向至該網址。這個網址必須是 OAuthGetRequestToken 要求的 oauth_callback 參數，以及 OAuthGetAccessToken 要求的 verifier 參數。

為了改善使用者體驗，應用程式應嘗試自動偵測使用者何時重新導向至該網址，並立即導向前景，並發出 OAuthGetAccessToken 要求完成 OAuth 程序。

如需進一步瞭解相關資訊和最佳做法，請參閱自動偵測核准。

如果您的應用程式無法自動偵測使用者重新導向至回呼網址，或是無法將自己導向前景，回呼網址應顯示頁面，說明如何將應用程式移至前景，以及如何在應用程式中啟動 OAuthGetAccessToken 要求。

裝置模式

如果您的應用程式無法啟動完整網路瀏覽器，您也可以讓複合式用戶端裝置在沒有網路瀏覽器的情況下進行授權。

這個模式可讓開發人員設定網站，讓使用者能夠授權存取要求。授權之後，使用者會收到 Google 產生的代碼，並將他們重新導向至開發人員網站。網站應向使用者說明如何將代碼輸入裝置，以完成授權程序。

開發模式

這個模式只適合在應用程式初期開發期間使用。

如同 AutoDetect 模式，您的應用程式必須啟動瀏覽器，而使用者必須授權您的要求。不過，您不必為回呼網址建立網頁，而是將 oauth_callback 參數的值設為 "oob" (超出頻帶)。

使用者授權要求之後，Google 會將使用者導向至顯示驗證碼號碼的 Google 帳戶頁面 (請參閱範例)。

您必須先返回您的應用程式並輸入驗證編號，才能提出 OAuthGetAccessToken 要求。

進一步瞭解 OAuth

若要進一步瞭解 Google 的 OAuth 導入方式，包括如何註冊應用程式及建立必要的 OAuth 參數，請參閱以下其他資源：

• 使用 OAuth 搭配 Google Data API 用戶端程式庫
• 文章：將 OAuth 與 Google Data API 搭配使用，包括 OAuth Playground 說明。這項互動工具可用於試用 OAuth。
• 已安裝應用程式的 OAuth (完整說明文件)
• 產生金鑰和憑證
• OAuth 規格

返回頁首

使用 AuthSub 授權

AuthSub 是 Google 專屬的授權 API，可做為大多數 Google API 的 OAuth 替代方案。請盡量避免使用 AuthSub。如果您的應用程式已經採用 AuthSub，請改用 OAuth 或混合式通訊協定。

AuthSub 授權程序

使用 AuthSub 授權涉及三個實體之間的交互作用：網路應用程式、Google 服務與使用者。下圖說明序列：

1. 當網路應用程式需要存取使用者的 Google 服務時，它會呼叫 Google 的 Authorization Proxy 服務。
2. 「授權」服務會回應「存取要求」頁面來做出回應。這個 Google 代管的網頁會提示使用者授予/拒絕 Google 服務的存取權。系統可能會要求您先登入自己的帳戶。
3. 使用者決定授予或拒絕網路應用程式的存取權限。使用者拒絕存取時，系統會將他們導向 Google 網頁，而不是返回網路應用程式。
4. 如果使用者授予存取權，授權服務會將使用者重新導向回網路應用程式。該重新導向包含一種授權憑證，適合長期使用。您可以將其改成長久使用的憑證。
5. 網頁應用程式將請求與 Google 服務聯絡，並使用授權權杖做為使用者的代理程式。
6. 如果 Google 服務可識別該權杖，會提供要求的資料。

使用 AuthSub

如要將 AuthSub 整合至網路應用程式中，必須完成以下工作：

1. 決定是否要註冊您的網頁應用程式。

   Google 可以識別已註冊的網頁應用程式；Google 登入頁面向使用者顯示的標準警告內容會遭到修改或省略。此外，已註冊的網頁應用程式會以描述性名稱來辨識，而不僅僅是呼叫網址。請注意，部分 Google 服務只允許未註冊的網路應用程式存取。如果您選擇註冊，請使用這個自動化的註冊程序。

   如果註冊成功，您也可以提供安全性憑證和金鑰。已註冊且具備憑證的網路應用程式可以取得來自 Google 服務的資料，以便使用安全的憑證。(必要時也可使用不安全的憑證)。

2. 決定要使用的權杖類型及管理權杖的方式。

   Google 收到授權憑證的目的在於，如果日後與該使用者進行指定的 Google 服務互動，就會使用該授權權杖。您選擇的憑證類型 (單一用途或工作階段使用) 取決於網路應用程式與 Google 服務的互動類型。舉例來說，如果互動是一次性或罕見的事件，只需使用單次使用的權杖即可。

   如果您選擇取得工作階段符記，並定期使用這些憑證存取 Google 服務，您的網路應用程式就必須管理憑證儲存空間，包括追蹤使用者和有效憑證的 Google 服務。「Google 帳戶」無法管理大量權杖，但實際上，每個網頁應用程式和每位使用者最多只能有十個有效的憑證。這項限制可讓網路應用程式在需要時取得多個憑證來支援不同的服務；不過，它並不需要在每次網路應用程式存取 Google 服務時取得新的憑證。如果您決定儲存工作階段符記，憑證應視為安全儲存在伺服器上的任何其他機密資訊，

   或者，只要您建立了憑證撤銷機制，就可以選擇定期取得新的憑證。您的應用程式必須先撤銷現有的憑證，才能要求其他憑證。這種情況下，每當使用者要求新權杖時，使用者都必須登入並授予存取權。

3. 判斷要存取的 Google 服務需要的範圍。

   每項 Google 服務可決定所允許的存取權類型和類型。此存取權以範圍值表示。用來指定整個服務的簡易網址，也可以指定較為受限的存取權。某些服務會限制存取權限，例如允許存取有限的唯讀資訊。如要取得您要存取的 Google 服務允許的範圍，請參閱該服務的說明文件。建議您要求最嚴格的範圍。舉例來說，如果您嘗試存取 Gmail 的 Atom 資訊提供功能，請使用「http://www.google.com/calendar/feeds/」範圍，而不要使用「http://www.google.com/calendar/」。對於大範圍要求，Google 服務更加嚴格。

4. 設定用於要求及接收授權權杖的機制。

   機制必須產生格式正確的 AuthSubRequest 呼叫，包括指定適當的「next」和「scope」網址值 (如步驟 3 所示)。如果您使用的是安全權杖且/或管理工作階段符記，該要求也必須包含這些變數的值。

   下一個網址可以包含查詢參數。例如，支援多種語言時，請加入查詢參數，以識別使用者所查看的網路應用程式版本。下一個 值為 http://www.yoursite.com/Retrievetoken?Lang=de 會導致重新導向 http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE。剖析權杖與 Lang 參數可確保使用者重新導向到正確的網站版本。

   在某些情況下，如果系統要求使用者在 Google 帳戶網站上授予存取權，請使用 hd 參數來簡化使用者的體驗。在多數情況下，您只要進行簡單的步驟，即可登入自己的帳戶，並選擇是否要授予存取權。但是，擁有多個 Google 帳戶 (一般 Gmail 帳戶和/或一或多個 Google Apps 代管帳戶) 的使用者，可能需要按照額外的「通用登入」程序，找出想要存取的帳戶。如果您的應用程式是專為特定代管網域設計，您可以使用這個參數來辨識該網域，如果您的應用程式可存取未在代管服務中使用的服務，那麼您也可以使用 hd 參數。如果將值設為「default」，可限制只有一般帳戶可以進行授權。設定 hd 值之後，Google 會自動選取正確的帳戶進行授權。

   權杖機制必須可用來剖析來自 Google 的重新導向，其中包含單次使用權杖，並對其執行操作。由於授權權杖只適用於使用者，因此您的應用程式必須能夠將憑證與使用者建立關聯。建議在發出憑證要求前，先向使用者發出一個 Cookie。這樣一來，當 Google 將使用者重新導向至附加的網站時，您的應用程式就能讀取 Cookie，並將該權杖與正確的使用者識別資訊建立關聯。

5. 設定用於要求工作階段符記的機制，並視需要儲存或撤銷這些憑證。

   視您在步驟 2 中決定的符記管理決策而定，您可能需要建立機制來取得及撤銷工作階段符記 (AuthSubSessionToken 和 AuthSub 撤銷 Token)。如要測試工作階段和撤銷機制，請使用 AuthSubTokenInfo 表示特定憑證是否有效。儲存憑證時，應用程式必須同時追蹤憑證涵蓋的使用者 ID 和服務 (範圍)。

6. 設定存取 Google 服務機制的機制。

   請參閱 Google 服務的說明文件，瞭解適當的要求格式。所有向 Google 服務發出的要求都必須包含有效的授權權杖。一般來說，向 Google 服務發出的要求會以 HTTP GET 的形式呈現 (如果寫入新資料則使用 POST)，要求標頭中會參照符記。

   要求標頭應採用以下形式：

   Authorization: AuthSub token="token"

   如果是憑證，則必須附上數位簽章。如需操作說明和範例，請參閱「簽署要求」一節。

   下方範例會說明呼叫「Google 日曆」資訊提供服務的要求標頭。這個要求含有不安全的權杖：

   GET /calendar/feeds/default/private/full HTTP/1.1
   Content-Type: application/x-www-form-urlencoded
   Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
   User-Agent: Java/1.5.0_06
   Host: www.google.com
   Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
   Connection: keep-alive

進一步瞭解 AuthSub

如需 AuthSub 的相關資訊，包括向 Google 註冊您的應用程式，以及關於將一次性憑證交換成憑證憑證的詳細說明，請參閱下列其他資源：

• 網路應用程式的 AuthSub 驗證 (完整說明文件)
• 搭配 Google Data API 用戶端程式庫使用 AuthSub
• 產生金鑰和憑證 (安全的 AuthSub)
• 使用 AuthSub 簽署要求 (安全 AuthSub)
• 網頁式應用程式的註冊

返回頁首

使用 ClientLogin 授權

ClientLogin 是 Google 專屬的授權 API，可做為大部分 Google API 的 OAuth 替代方案。請盡量避免使用 ClientLogin。如果您已經在使用 ClientLogin 的應用程式，則應改用 OAuth 或混合式通訊協定。

為已安裝的應用程式進行驗證：ClientLogin

ClientLogin 可讓您的使用者在應用程式內登入自己的 Google 帳戶。應用程式會透過登入資料與 Google 聯絡，要求存取指定的 Google Data API。成功驗證登入資訊後，Google 會在每次使用者要求存取使用者帳戶時，提供一個權杖，例如取得或發布資料。這組憑證會在指定時間內有效 (視您使用的 Google 服務而定)。

注意：Google Data API 用戶端程式庫提供一種方法，可協助您在已安裝的應用程式中使用 ClientLogin。具體來說，您可以透過以下方法取得驗證權杖、處理人機驗證 (Captcha) 驗證、喚回驗證權杖以供日後使用，並在每個要求中傳送正確的 Authorization 標頭。如果您使用的是其中一個程式庫，請參閱搭配 Google Data API 用戶端程式庫使用 ClientLogin 一文。

ClientLogin 授權程序

以 ClientLogin 進行授權時，涉及三種實體 (已安裝應用程式、Google 服務和使用者) 之間的一系列互動。下圖說明序列：

1. 當第三方應用程式需要存取使用者的 Google 服務時，就會擷取使用者的登入名稱和密碼。
2. 然後，第三方應用程式會呼叫 ClientLogin，呼叫 Google 的授權服務。
3. 如果 Google 授權服務認定需要額外審核，就會傳回人機驗證 (Captcha) 憑證以「人機驗證」(Captcha) 映像檔傳回「失敗」回應。
4. 如果收到人機驗證 (Captcha) 驗證問題，第三方應用程式就會顯示人機驗證 (Captcha) 圖片並向使用者顯示的答案。
5. 使用者應要求回答人機驗證 (Captcha) 驗證問題。
6. 第三方應用程式會發出新的 ClientLogin 呼叫，此時包括人機驗證 (Captcha) 答案和憑證 (收到失敗回應)。
7. 如果嘗試登入成功 (無論是否有人機驗證 (Captcha) 驗證)，Google 授權服務會傳回憑證給應用程式。
8. 應用程式會要求 Google 服務提出資料存取要求，參照從 Google Authorization 服務收到的憑證。
9. 如果 Google 服務可識別該權杖，它會提供您要求的資料存取權。

使用 ClientLogin

在您的已安裝應用程式中使用這個介面，透過程式存取使用者的 Google 帳戶。收集使用者的登入資訊後，請呼叫 ClientLogin 來要求存取使用者的帳戶。成功驗證登入資訊後，Google 會在每次使用者要求存取帳戶時，傳回一個請求碼。這組憑證會在指定時間內有效 (由您使用的 Google 服務定義)。

如要將 ClientLogin 整合至您的應用程式中，需要以下工作：

1. 建立使用者擷取登入資料的 UI 元素。

   這個使用者介面必須徵求使用者名稱 (包含網域的電子郵件地址) 與密碼。另外，使用者介面也應能使用 Google 收到的網址顯示人機驗證 (Captcha) 圖片 (如有必要)，並向使用者收集正確的答案。在理想情況下，您的使用者介面會附上 Google 帳戶登入頁面 (「https://www.google.com/accounts/Login」) 的連結，方便使用者在申請新帳戶或進行其他帳戶維護作業時。

2. 撰寫程式碼以產生格式正確的 HTTPS POST ClientLogin 要求並傳輸。

   這個程式碼必須包含邏輯來處理人機驗證 (Captcha) 驗證問題，且必須同時加入 logintoken 和 logincaptcha 參數。應用程式應該要能偵測使用者何時遺漏了必要資訊，或在登入失敗後重複提供不正確的資料，並在不傳送過多要求的情況下顯示錯誤。

3. 處理 Google 的回應。

   登入要求有四種可能的回應：

   • 成功 (HTTP 200)
   • 出現錯誤 (HTTP 403) 及相關說明錯誤碼
   • 要求無效，通常是因為格式錯誤的要求
   • 人機驗證 (Captcha) 驗證失敗

   成功回應中包含標示為「Auth」的授權權杖。所有向這個帳戶發出的 Google 服務請求都必須包含這個權杖。授權權杖應受到嚴密的保護，而且不應向其他應用程式提供，因為這些權限代表使用者帳戶的存取權。權杖時間限制會因核發哪個服務而有所不同。

   失敗回應包括一或多個錯誤代碼，以及可向使用者顯示的錯誤訊息網址。請注意，由於密碼不正確或使用者名稱不明確 (例如使用者尚未註冊帳戶)，ClientLogin 不會區別失敗情形。應用程式必須視情況處理所有可能出現的錯誤訊息。

   如果無法通過人機驗證 (Captcha) 驗證，Google 基於任何原因決定應採取額外的安全性措施。此回應會與人機驗證 (Captcha) 映像檔網址以及一組代表特定人機驗證 (Captcha) 驗證的權杖搭配使用。

4. 處理 Google 的人機驗證 (Captcha) 驗證問題。

   如要處理驗證問題，應用程式必須顯示人機驗證 (Captcha) 圖片，並要求使用者回答。如要顯示人機驗證 (Captcha) 圖片，請使用傳回失敗回應的 CaptchaUrl 值，並在前面加上 Google 帳戶網址，例如：http://www.google.com/accounts/。使用者提供答案後，應用程式應重新傳送登入要求，這次要求包括人機驗證 (Captcha) 權杖 (logintoken) 和使用者的答案 (logincaptcha)。Google 會在提供使用者帳戶存取權前驗證使用者的答案。

   如果開發人員不想管理接收和傳送使用者人機驗證 (Captcha) 回應的程序，可以採用替代方案。為因應人機驗證 (Captcha) 驗證問題，應用程式可以將使用者導向 Google 代管的網頁：「https://www.google.com/accounts/DisplayUnlockCAPTCHA」。使用者成功回應挑戰後，Google 伺服器會信任目前使用的電腦。接著，應用程式可以重新傳送原先的登入要求以取得授權權杖。

注意：Google 不會在驗證人機驗證 (Captcha) 前驗證登入嘗試。這表示即使進行人機驗證 (Captcha) 驗證，登入嘗試也可能會失敗。

* 人機驗證 (Captcha) 是卡內基梅隆大學 (Carnegie Mellon University) 的商標

返回頁首

小工具驗證

OAuth Proxy

如果您是使用標準 Widgets API 來建立小工具，則可使用名為 OAuth OAuth 的小工具平台功能來存取 Google Data API。OAuth (如上所述) 是一種驗證標準，可讓使用者在小工具代管服務 (例如 iGoogle、MySpace 或 Orkut) 中存取自己的私人資料，或與其他網站或小工具分享個人資料。OAuth Proxy 可以隱藏許多 OAuth 的驗證詳細資料，讓小工具開發人員更容易進行開發作業。該 Proxy 是以名為 Shindig 的開放原始碼專案為基礎，這是實作小工具規格的實作專案。

注意：只有使用 gadgets.* API 且在 OpenSocial 容器中執行的小工具才支援 OAuth Proxy。舊版小工具 API 不支援這項功能。

驗證流程

您的小工具必須取得 OAuth 憑證，才能存取使用者資料。OAuth Proxy 會為您管理驗證流程。使用者初次安裝您的小工具時，系統會執行下列程序：

1. 您的小工具第一次載入時，會嘗試使用其中一種 Google Data API 存取使用者資料。
2. 使用者尚未授予存取權，因此要求失敗。回應物件含有 OAuth 核准頁面的網址 (response.oauthApprovalUrl)。您的小工具應提供以此網址啟動新視窗的方法。
3. 在核准網頁上，使用者選擇授予或拒絕您的小工具存取權。如果成功，系統會將使用者帶往您指定的 oauth_callback 頁面。為了提供最佳使用者體驗，請使用 http://oauth.gmodules.com/gadgets/oauthcallback。
4. 接著，使用者關閉彈出式視窗。如要通知小工具使用者已獲得核准，可以使用彈出式視窗處理常式來偵測核准期間的關閉情況。此外，您的小工具還可以顯示一個連結 (例如「我已核准存取」)，讓使用者可在這個視窗關閉後點擊。
5. 您的小工具會再次要求存取使用者資料，嘗試再次存取 Google Data API。嘗試成功。
6. 您的小工具已通過驗證，可以正常執行。

小工具設定

如要使用一或多個 Google Data API，您必須先告知小工具使用 OAuth 做為驗證方法。在小工具 XML 的 <ModulePrefs> 區段中新增 <OAuth> 元素：

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

在本節中，請只變更下列查詢參數：

scope

要求網址中的必要參數。您的小工具可以存取這項參數中使用的 scope 資料。在這個範例中，小工具可以存取 Blogger 和「Google 日曆」資料。小工具可以要求單一範圍或多個範圍的資料，如本例所示。

oauth_callback

「授權網址」中的選用參數。在使用者核准資料存取權後，OAuth 核准網頁會重新導向至這個網址。您應該將這個參數設為 http://oauth.gmodules.com/gadgets/oauthcallback，以便在使用者安裝您的小工具時，提供最佳的使用者體驗。這個網頁會提供一段會自動關閉彈出式視窗的 JavaScript 程式碼。您也可以將這個參數設為自己的「已核准」網頁，也可以將參數留白。

存取經過驗證的 Google Data API 資訊提供

小工具驗證您的使用者後，您就可以透過 Google Data API JavaScript 用戶端程式庫輕鬆存取 Google Data API。如要瞭解如何在 OAuth Proxy 中使用程式庫，請參閱使用 JavaScript 用戶端程式庫。

進一步瞭解小工具

如需建立 Google Data API 小工具的完整資訊，包括 OAuth Proxy 的入門資訊、入門入門文章和 gadgets.* 規格，請參閱下列其他資源：

• 使用 JavaScript 用戶端程式庫
• 建立 Google Data API 小工具 (文章)
• 撰寫 OAuth 小工具 (完整的小工具說明文件)
• Widgets API 說明文件

返回頁首