Google Data Protocol 中的驗證和授權

警告：本頁面介紹的是 Google 舊版 API (Google Data API)，僅適用於Google Data API 目錄中列出的 API，其中許多 API 已由新版 API 取代。如要瞭解特定新版 API，請參閱該 API 的說明文件。如要瞭解如何使用較新的 API 授權要求，請參閱「Google 帳戶驗證和授權」。

第三方應用程式通常需要有限的 Google 帳戶存取權，才能執行特定類型的活動。為確保使用者資料不會遭到濫用，所有存取要求都必須經過帳戶持有人核准。存取權控管包含驗證和授權兩個部分。

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

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

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

第三方應用程式可透過 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 登入」。

已淘汰的服務 AuthSub、ClientLogin 和 OAuth 1.0 可做為部分 Google API 的 OAuth 2.0 替代方案。如 2012 年公告所述，我們將於 2015 年 4 月 20 日關閉這些已淘汰的服務。如果您現有的應用程式使用這些方法，請遷移至 OAuth 2.0。

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

注意：本文旨在概略說明每種驗證方法。如要瞭解各項方法的詳細資訊，請參閱完整的 Google 帳戶驗證 API 說明文件。

如要討論如何使用 Google 帳戶 API，請參閱 Google 帳戶 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 應用程式帳戶相關聯的資料，可以使用 Google 實作的 OAuth API。如要完整瞭解如何為網頁應用程式導入 OAuth，包括範例，請參閱「網頁應用程式適用的 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

如要設定應用程式，透過 OAuth 使用 Google 授權服務，請先完成下列工作。

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

如要進一步向使用者保證資料安全，您可以選擇向 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 服務，您可以取得多個存取權杖，但每位使用者和應用程式在任何時間點最多只能有 10 個未使用的存取權杖。

如果應用程式支援多個使用者帳戶，您必須追蹤每個權杖與哪個帳戶相關聯。 每個 OAuth 權杖都專屬於授權存取權的使用者。應用程式必須能將權杖與正確的使用者建立關聯。其中一種做法是在提出權杖要求前，先向使用者發放 Cookie。使用者授予存取所要求資料的權限後，Google 會傳送授權要求權杖，並將使用者重新導向至您的應用程式。接著，您可以使用應用程式的 Cookie，將權杖與正確的使用者建立關聯。

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

對 Google 服務的每項要求都必須經過簽署，且必須包含有效的 OAuth 存取權杖。一般來說，每項要求都是以 HTTP GET 要求的形式提出，標頭中會包含存取權杖和簽章。如要寫入新資料，要求應使用 HTTP POST。

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

導入 OpenID (選用)

如果您要實作 OpenID 進行使用者驗證，請考慮使用混合通訊協定合併這兩個程序。使用 OpenID+OAuth 時，系統會將取得要求權杖和授權權杖的工作，視為 OpenID 要求的一部分，並搭配 OAuth 擴充功能處理。與 OAuthGetRequestToken 相同，這些擴充功能可用於識別要存取的 Google 服務。OpenID 要求成功的回應會包含授權要求權杖。收到這個權杖後，請使用 OAuthGetAccessToken 將其換成存取權杖。

使用 OAuth 權杖

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

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

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

您可以在 OAuth Playground 中，試著要求及接收授權權杖。

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

設定回呼網址

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

舉例來說，如果支援多種語言，您可以加入查詢參數，識別使用者查看的應用程式版本。如果 oauth_callback 值為「http://www.yoursite.com/Retrievetoken?Lang=de」，系統會將使用者重新導向至「http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE」。剖析權杖和語言參數，可確保使用者重新導向回正確版本的網站。

如果未加入 oauth_callback 參數，Google 會在授權您的存取要求後，將使用者導向顯示驗證碼的網頁 (請參閱範例)。使用者必須手動返回您的應用程式並輸入驗證碼，您才能取得授權要求權杖。

向使用者識別您的應用程式

Google 通常會在向使用者要求存取權同意聲明時，顯示應用程式名稱 (請參閱範例)。

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

如果應用程式已註冊，請勿設定這項參數。根據預設，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

如要設定應用程式，透過 OAuth 使用 Google 授權服務，請先完成下列工作。

判斷應用程式將存取的資料範圍

各項 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 會顯示「anonymous」字串。

注意：如要在 OAuth Playground 中設定 xoauth_displayname 參數，請先勾選「進階」方塊，再擷取要求權杖。

啟動網路瀏覽器

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

• 大多數應用程式都應使用 AutoDetect 模式
• 如果應用程式無法啟動完整網路瀏覽器，就應使用裝置模式。
• 開發模式僅適用於早期開發階段。

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 的授權 Proxy 服務發出 AuthSub 呼叫。
2. 授權服務會提供「存取要求」頁面做為回應。這個由 Google 管理的頁面會提示使用者授予/拒絕存取 Google 服務的權限。系統可能會先要求使用者登入帳戶。
3. 使用者可決定是否要授予網頁應用程式存取權。如果使用者拒絕存取權，系統會將他們導向 Google 網頁，而非返回網頁應用程式。
4. 如果使用者授予存取權，授權服務會將使用者重新導向回網頁應用程式。重新導向包含一次性授權權杖，可交換為長期有效權杖。
5. 網頁應用程式會使用授權權杖做為使用者的代理程式，向 Google 服務發出要求。
6. 如果 Google 服務可辨識權杖，就會提供要求的資料。

使用 AuthSub

如要在網路應用程式中整合 AuthSub，請完成下列工作：

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

   註冊的網路應用程式可享有 Google 辨識的優勢，Google 登入頁面顯示給使用者的標準警語會經過修改或省略。此外，系統會以描述性名稱識別已註冊的網路應用程式，而非僅使用呼叫網址。請注意，部分 Google 服務只允許未註冊的 Web 應用程式有限存取。如要註冊，請使用這項自動化註冊程序。

   註冊時，您也可以提供安全憑證和金鑰。已註冊且有憑證的網路應用程式可取得安全權杖，用於向 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 中決定)。如果您使用安全權杖和/或管理工作階段權杖，要求也必須包含這些變數的值。

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

   在某些情況下，使用 hd 參數可簡化使用者在 Google 帳戶網站上授予存取權的流程。在多數情況下，只要登入帳戶並選擇是否授予存取權，即可完成程序。不過，如果使用者擁有多個 Google 帳戶 (一般 Gmail 帳戶和/或一或多個 Google 應用程式代管帳戶)，可能需要完成額外的「通用登入」程序，才能指定要存取的帳戶。如果應用程式是為特定受管理網域設計，您可以使用這個參數識別該網域，免除這些額外步驟。如果應用程式存取的服務不適用於代管帳戶，您也可以使用 hd 參數，將值設為「default」即可限制授權僅適用於一般帳戶。設定 hd 值後，Google 會自動選取正確的帳戶進行授權。

   權杖機制必須能夠剖析從 Google 收到的重新導向，其中包含一次性權杖，並根據該權杖採取行動。由於授權權杖專屬於使用者，應用程式必須能夠將權杖與使用者建立關聯。建議您先向使用者發放 Cookie，再提出權杖要求。接著，當 Google 將使用者重新導向至您的網站，並附加權杖時，您的應用程式可以讀取 Cookie，並將權杖與正確的使用者 ID 建立關聯。

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

   視您在步驟 2 中做出的權杖管理決策而定，您可能需要建立機制來取得及撤銷工作階段權杖 (AuthSubSessionToken 和 AuthSubRevokeToken)。如要測試工作階段和撤銷機制，請使用 AuthSubTokenInfo，這個方法會指出指定符記是否有效。如果儲存權杖，應用程式必須追蹤使用者 ID 和權杖涵蓋的服務 (範圍)。

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

   如要瞭解正確的要求格式，請參閱 Google 服務的說明文件。所有傳送至 Google 服務的要求都必須包含有效的授權權杖。一般來說，對 Google 服務的要求會採用 HTTP GET 形式 (如果是寫入新資料，則為 POST)，且要求標頭中會參照權杖。

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

   Authorization: AuthSub token="token"

   其中 token 是授權權杖，為單次使用或工作階段權杖，由 Google 在回應 AuthSub 要求時提供。如果符記安全無虞，則必須附上數位簽章。如需操作說明和範例，請參閱「簽署要求」。

   以下範例說明呼叫 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 標頭。如果您使用其中一個程式庫，請參閱「使用 ClientLogin 搭配 Google Data API 用戶端程式庫」。

ClientLogin 授權程序

使用 ClientLogin 授權時，安裝的應用程式、Google 服務和使用者之間會進行一連串的互動。下圖說明此順序：

1. 第三方應用程式需要存取使用者的 Google 服務時，會擷取使用者的登入名稱和密碼。
2. 接著，第三方應用程式會向 Google 的授權服務發出 ClientLogin 呼叫。
3. 如果 Google 授權服務認為需要額外審查，就會傳回含有 CAPTCHA 權杖和驗證問題的失敗回應，並以 CAPTCHA 圖片的網址形式呈現。
4. 如果收到人機驗證問題，第三方應用程式會向使用者顯示人機驗證圖片，並要求使用者回答。
5. 如果系統要求，使用者會提交人機驗證問題的答案。
6. 第三方應用程式會發出新的 ClientLogin 呼叫，這次會包含 CAPTCHA 答案和權杖 (透過失敗回應接收)。
7. 登入嘗試成功後 (無論是否通過人機驗證)，Google 授權服務都會將權杖傳回應用程式。
8. 應用程式會向 Google 服務傳送資料存取要求，並參照從 Google 授權服務收到的權杖。
9. 如果 Google 服務可辨識權杖，就會提供要求的資料存取權。

使用 ClientLogin

在已安裝的應用程式中使用這個介面，以程式輔助方式存取使用者的 Google 帳戶。向使用者收集登入資訊後，請呼叫 ClientLogin，要求存取使用者的帳戶。登入資訊通過驗證後，Google 會傳回權杖，應用程式每次要求存取使用者帳戶時，都會參照這個權杖。權杖在一段時間內有效，有效時間長度取決於您使用的 Google 服務。

如要在應用程式中加入 ClientLogin，請完成下列工作：

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

   使用者介面必須要求使用者提供名稱 (包括網域的電子郵件地址) 和密碼。 如果需要，使用者介面也應能使用從 Google 收到的網址顯示人機驗證圖片，並要求使用者提供正確答案。理想情況下，如果使用者需要註冊新帳戶或進行其他帳戶維護作業，您的 UI 會包含 Google 帳戶登入頁面 (「https://www.google.com/accounts/Login」) 的連結。

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

   這段程式碼必須包含處理人機驗證問題的邏輯，並納入 logintoken 和 logincaptcha 參數。應用程式也應能偵測使用者何時省略必要資訊，或在登入失敗後重複輸入錯誤資料，並顯示錯誤訊息，不必傳送多餘的要求。

3. 處理 Google 的回覆。

   登入要求可能會產生以下四種回應：

   • 成功 (HTTP 200)
   • 失敗 (HTTP 403)，並附上說明錯誤代碼
   • 要求無效，通常是因為要求格式錯誤
   • 無法通過人機驗證 (Captcha) 挑戰

   成功的回應會包含標示為「Auth」的授權權杖。這個權杖必須包含在後續對這個帳戶的 Google 服務提出的所有要求中。授權權杖代表使用者帳戶的存取權，因此請務必妥善保管， 切勿提供給任何其他應用程式。權杖的時間限制取決於發行權杖的服務。

   失敗回應會包含一或多個錯誤代碼，以及含有錯誤訊息的網址，可向使用者顯示。請注意，ClientLogin不會區分密碼錯誤或使用者名稱無法辨識 (例如使用者尚未註冊帳戶) 所造成的失敗。您的應用程式必須適當處理所有可能的錯誤訊息。

   如果失敗回應包含人機驗證問題，表示 Google 認為無論如何都應採取額外的安全措施。這項回應會附上人機驗證圖片網址，以及代表特定人機驗證問題的權杖。

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

   如要處理這項挑戰，應用程式必須顯示人機驗證圖片，並要求使用者提供答案。如要顯示 CAPTCHA 圖片，請使用失敗回應傳回的 CaptchaUrl 值，並加上 Google 帳戶網址前置字串：「http://www.google.com/accounts/」。使用者提供答案後，應用程式應重新傳送登入要求，這次要包含 CAPTCHA 權杖 (logintoken) 和使用者的答案 (logincaptcha)。Google 會先驗證使用者的答案，再授權存取帳戶。

   如果開發人員不想管理取得及傳輸使用者 CAPTCHA 回應的程序，可以改用其他方式。應用程式可以將使用者導向 Google 代管的頁面「https://www.google.com/accounts/DisplayUnlockCaptcha」，回應人機驗證問題。使用者成功回應驗證後，Google 伺服器就會信任使用的電腦。應用程式隨後可以重新傳送原始登入要求，以取得授權權杖。

注意：Google 不會在發出人機驗證問題前驗證登入嘗試。這表示即使通過人機驗證，登入嘗試仍可能失敗。

* CAPTCHA 是卡內基美隆大學的商標

返回頁首

小工具的驗證

OAuth Proxy

如果您使用標準 Gadgets API 建構小工具，可以運用小工具平台的 OAuth Proxy 功能存取 Google Data API。OAuth (如上所述) 是一種驗證標準，可讓使用者存取 iGoogle、MySpace 或 Orkut 等小工具代管服務中的私人資料，或與其他網站或小工具共用資料。OAuth Proxy 的設計宗旨是隱藏許多 OAuth 驗證詳細資料，讓 Gadget 開發人員更輕鬆地進行開發。Proxy 是以名為 Shindig 的開放原始碼專案為基礎，該專案實作了 Gadget 規格。

注意：OAuth Proxy 僅支援使用 gadgets.* API 且在 OpenSocial 容器中執行的 Gadget。舊版小工具 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 小工具 (完整的小工具說明文件)
• Gadgets API 說明文件

返回頁首