帳戶連結使用業界標準 OAuth 2.0 隱含與授權碼流程。您的服務必須支援符合 OAuth 2.0 規定的授權和憑證交換端點。
在「暗示」流程中,Google 會在使用者的瀏覽器中開啟您的授權端點。成功登入後,會將長期存取憑證傳回 Google。目前從 Google 發出的每個要求都會包含這個存取憑證。
在「授權碼」流程中,您需要兩個端點:
Authorization 端點,可為尚未登入的使用者顯示登入 UI。授權端點也會建立短期的授權碼來記錄使用者。同意要求的存取權。
憑證交換端點,該端點負責兩種交換類型:
- 將授權碼提供給長期使用憑證和短期存取憑證。當使用者完成帳戶連結流程時,系統就會執行這個交換作業。
- 針對短期存取權杖交換長期更新權杖。 如果 Google 需要這個存取憑證過期,因此需要進行這個交換作業。
選擇 OAuth 2.0 流程
雖然隱含流程比較簡單,但 Google 建議採用隱含流程所核發的存取憑證永遠不會過期。這是因為憑證在隱含流程到期後,必須強制重新連結帳戶。如果您需要基於安全考量而要求憑證過期,強烈建議您改用授權碼流程。
設計指南
本節說明您針對 OAuth 連結流程託管的使用者畫面設計要求和建議。在 Google 應用程式呼叫 API 後,您的平台會向使用者顯示登入 Google 頁面和帳戶連結同意畫面。使用者同意連結帳戶之後,系統就會將他們重新導向 Google 的應用程式。
必要條件
- 您必須通知使用者的帳戶將連結至 Google,而不是特定的 Google 產品,例如 Google Home 或 Google 助理。
建議
建議您採取下列做法:
顯示 Google 的隱私權政策。在同意畫面中加入 Google 隱私權政策連結。
要分享的資料。使用簡明扼要的用詞告訴使用者 Google 需要哪些資料,以及收集這些資料的原因。
加入明確的行動號召。在同意畫面上註明明確的行動號召 (例如「同意和連結」)。這是因為使用者必須瞭解需要與 Google 分享哪些資料,才能連結自己的帳戶。
取消功能:如果使用者選擇不要進行連結,可以提供取消或取消訂閱的方式。
清除登入程序。確保使用者明確能登入 Google 帳戶,例如使用者名稱和密碼欄位或使用 Google 帳戶登入欄位。
取消連結。提供機制,讓使用者能取消連結,例如 您平台中帳戶設定的網址。您也可以加入 Google 帳戶連結,方便使用者管理已連結帳戶。
可變更使用者帳戶。建議使用者切換帳戶的方法。如果使用者經常擁有多個帳戶,這項功能就特別實用。
- 如果使用者必須先關閉同意畫面才能切換帳戶,請將可復原的錯誤傳送給 Google,讓使用者可透過 OAuth 連結和隱含流程登入所需帳戶。
加入您的標誌。在同意畫面中顯示公司標誌。 請善用樣式指南來放置標誌。如果您希望一併顯示 Google 的標誌,請參閱標誌和商標一文。
建立專案
如要建立專案以使用帳戶連結功能,請按照下列步驟操作:
- Go to the Google API Console.
- 單擊創建項目 。
- 輸入名稱或接受生成的建議。
- 確認或編輯所有剩餘字段。
- 點擊創建 。
要查看您的項目ID:
- Go to the Google API Console.
- 在登錄頁面的表格中找到您的項目。項目ID出現在ID列中。
設定 OAuth 同意畫面
Google 帳戶連結程序包含同意畫面,可告知使用者應用程式要求存取資料、要求的資料類型和適用的條款。您必須先設定 OAuth 同意畫面,才能產生 Google API 用戶端 ID。
- 開啟 Google API 控制台的「OAuth 同意畫面」頁面。
- 如果出現提示,請選取您剛建立的專案。
在「OAuth 同意畫面」頁面上,填寫表單,然後按一下「Save」按鈕。
Application name (應用程式名稱):要求同意的應用程式名稱。名稱必須如實反映您的應用程式,並與使用者在其他地方看到的應用程式名稱一致。應用程式名稱會顯示在「帳戶連結同意」畫面中。
應用程式標誌:可協助使用者識別您應用程式的圖片。這個標誌會顯示在帳戶連結同意畫面和帳戶設定中
支援電子郵件:方便使用者與您聯絡,詢問同意聲明問題。
Google API 的範圍:「範圍」可讓應用程式存取使用者的私人 Google 資料。就 Google 帳戶連結的情況而言,預設範圍 (電子郵件、設定檔、openid) 就已足夠,您不需要新增任何敏感範圍。一般而言,最佳做法是逐步要求範圍,且在需要時而非預先存取權。瞭解詳情。
授權網域:為了保護您和您的使用者,Google 僅允許透過 OAuth 進行驗證的應用程式使用授權網域。您的應用程式連結必須託管於授權網域。瞭解詳情。
應用程式首頁連結:應用程式的首頁。必須由授權網域代管。
應用程式隱私權政策連結:會顯示在 Google 帳戶連結同意畫面中。必須由授權網域代管。
應用程式服務條款連結 (選用):必須由授權網域代管。
圖 1. 虛構應用程式的 Google 帳戶連結同意畫面:Tunery
查看「驗證狀態」。若您的申請需要驗證,請按一下「提交驗證申請」按鈕,提交驗證申請。詳情請參閱「OAuth 驗證規定」一文。
實作 OAuth 伺服器
如要支援 OAuth 2.0 隱含流程,服務會進行授權 並可透過 HTTPS 存取端點這個端點會負責驗證 徵得使用者同意,才能存取資料。授權端點 為使用者提供未登入並記錄登入的登入使用者介面 同意授予請求的存取權。
當 Google 應用程式需要呼叫服務的其中一個已授權 API 時, Google 會使用這個端點,向使用者取得呼叫這些 API 的權限 管理。
由 Google 發起的一般 OAuth 2.0 隱含流程工作階段,是 下列流程:
- Google 會在使用者的瀏覽器中開啟授權端點。 使用者登入 (如果尚未登入),並將權限授予 Google 透過您的 API 存取他們的資料 (如果尚未授予權限)。
- 您的服務會建立存取權杖,並傳回給 Google。若要這麼做,請將使用者的瀏覽器重新導向回 Google,並授予存取權 附加至請求的權杖
- Google 會呼叫服務的 API,並將存取權杖附加至 每個要求您的服務會確認存取權杖是否已授予 Google 授權存取 API,然後完成 API 呼叫。
處理授權要求
Google 應用程式需要透過 OAuth 2.0 進行帳戶連結時 隱含流程時,Google 會將使用者傳送至您的授權端點, ,其中包含下列參數:
授權端點參數 | |
---|---|
client_id |
您指派給 Google 的用戶端 ID。 |
redirect_uri |
您傳送回應到這項要求的網址。 |
state |
傳回給 Google 的記帳金額,值維持不變 重新導向 URI |
response_type |
要在回應中傳回的值類型。以 OAuth 2.0 隱含
回應類型則一律為 token 。 |
user_locale |
中的 Google 帳戶語言設定 RFC5646 將內容翻譯成使用者慣用的語言。 |
舉例來說,如果您的授權端點位於
https://myservice.example.com/auth
,要求可能如下所示:
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE
如要讓授權端點處理登入要求,請按照下列步驟操作: 步驟:
確認
client_id
和redirect_uri
的值如下: 防止授予非預期或設定錯誤的用戶端應用程式存取權:- 確認
client_id
與您用戶端 ID 相符 而是指派給 Google - 確認
redirect_uri
指定的網址 參數的格式如下:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- 確認
檢查使用者是否已登入您的服務。如果使用者未簽署 的登入或申請流程。
產生供 Google 存取 API 的存取權杖。 存取權杖可以是任何字串值,但必須明確代表 以及該權杖適用的用戶端,且不可猜測。
傳送 HTTP 回應,將使用者的瀏覽器重新導向至網址 由
redirect_uri
參數指定。包含所有 網址片段中的下列參數:access_token
:您剛剛產生的存取權杖token_type
:字串bearer
state
:原始資料中未經修改的狀態值 要求
以下是最終網址的範例:
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
Google 的 OAuth 2.0 重新導向處理常式收到存取權杖並確認
state
值未變更。Google 取得
服務存取權杖,Google 會將該權杖附加到後續的呼叫
以便將 API 新增至 Service API
處理使用者資訊要求
userinfo 端點是 OAuth 2.0 受保護的資源,可傳回已連結使用者的聲明。除了下列用途外,不一定要實作並代管 userinfo 端點:
成功從權杖端點擷取存取權杖後,Google 會向您的使用者資訊端點傳送要求,以擷取已連結使用者的基本個人資料。
userinfo 端點要求標頭 | |
---|---|
Authorization header |
Bearer 類型的存取權杖。 |
舉例來說,如果您的 userinfo 端點位於
https://myservice.example.com/userinfo
,要求可能如下所示:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
為了讓 userinfo 端點處理要求,請按照下列步驟操作:
- 從授權標頭擷取存取權杖,然後為與存取權杖相關聯的使用者傳回資訊。
- 如果存取權杖無效,請使用
WWW-Authenticate
回應標頭傳回 HTTP 401 Unauthorized 錯誤。以下是 userinfo 錯誤回應的範例:HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
如果連結過程中傳回 401 未授權錯誤或其他失敗錯誤回應,將無法復原錯誤,擷取到的憑證將遭到捨棄,使用者必須再次啟動連結程序。 如果存取權杖有效,則傳回並傳回 HTTP 200 回應,且 HTTPS 內文含有下列 JSON 物件 回覆:
{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }
如果您的 userinfo 端點傳回 HTTP 200 成功回應,則會根據使用者的 Google 帳戶登錄擷取的權杖和憑證附加資訊。userinfo 端點回應 sub
用來在系統中識別使用者的專屬 ID。 email
使用者的電子郵件地址。 given_name
選填:使用者的名字。 family_name
選填:使用者的姓氏。 name
選填:使用者全名。 picture
選用:使用者的個人資料相片。
驗證實作
您可以通過使用驗證實現的OAuth 2.0遊樂場工具。
在工具中,執行以下步驟:
- 單擊配置 打開的OAuth 2.0配置窗口。
- 在OAuth流場中,選擇客戶端。
- 在OAuth端點字段中,選擇自定義。
- 在相應字段中指定您的 OAuth 2.0 端點和您分配給 Google 的客戶端 ID。
- 在步驟1部分,不要選擇任何谷歌範圍。相反,將此字段留空或鍵入對您的服務器有效的範圍(如果不使用 OAuth 範圍,則輸入任意字符串)。當您完成後,單擊授權的API。
- 在步驟2和步驟3段,完成OAuth 2.0流程和驗證每個步驟按預期工作。
您可以通過驗證您的實現谷歌帳戶鏈接演示工具。
在工具中,執行以下步驟:
- 點擊登錄在與谷歌按鈕。
- 選擇您要關聯的帳戶。
- 輸入服務標識。
- (可選)輸入您將請求訪問的一個或多個範圍。
- 單擊開始演示。
- 出現提示時,確認您可以同意並拒絕鏈接請求。
- 確認您被重定向到您的平台。