每個 Cloud-to-cloud 整合都必須包含驗證使用者的機制。
驗證功能可讓您將使用者的 Google 帳戶連結至驗證系統中的使用者帳戶。這樣一來，當你的服務端接收智慧住宅意圖時，你就能識別使用者。Google 智慧型家居僅支援 OAuth 授權碼流程。
本頁面說明如何設定 OAuth 2.0 伺服器，讓其與 Cloud-to-cloud 整合。
使用 OAuth 連結 Google 帳戶
在授權碼流程中，您需要兩個端點：
授權端點：會向尚未登入的使用者顯示登入 UI。授權端點也會建立短期授權碼，記錄使用者對於所要求存取權的同意。
權杖交換端點，負責兩種交換類型：
- 交換長期更新權杖和短期存取權杖的授權碼。這個交換作業會在使用者進行帳戶連結流程時發生。
- 將長效更新權杖交換為短期存取權杖。當 Google 需要新的存取權杖而因過期而需要新的存取權杖時，就會發生這個交換作業。
設計指南
本節說明針對您代管 OAuth 連結流程的使用者畫面設計規定和建議。Google 應用程式呼叫完畢後，您的平台便會向使用者顯示登入 Google 頁面和帳戶連結同意畫面。使用者同意連結帳戶後，系統就會將使用者導回 Google 應用程式。
需求條件
- 您必須說明使用者帳戶會連結至 Google，而「不是」連結至特定 Google 產品 (例如 Google Home 或 Google 助理)。
- 您必須擁有 Google 授權聲明，例如「登入，即表示您授權 Google 控制您的裝置」。請參閱《Google Home 開發人員政策》的「Google 裝置控制授權」一節。
- 當使用者選擇不連結時，您必須提供返回或取消連結的方式。
- 您必須開啟 Web OAuth 連結頁面，並確保使用者可透過清楚的方式登入 Google 帳戶，例如使用者名稱和密碼的欄位。請勿使用 Google 登入 (GSI) 方法，讓使用者不必將他們帶往網頁 OAuth 連結頁面即可進行連結。違反了 Google 政策。
建議
建議您採取下列做法：
顯示《Google 隱私權政策》。在同意畫面中加入《Google 隱私權政策》連結。
要分享的資料。以簡明扼要的用語告知使用者 Google 需要哪些資料以及要求的原因。
明確的行動號召。在同意畫面中顯示明確的行動號召，例如「同意並連結」。這是因為使用者必須瞭解必須和 Google 分享哪些資料才能連結帳戶。
可取消連結功能。提供讓使用者取消連結的機制，例如在您平台的帳戶設定網址。您也可以加入 Google 帳戶連結，方便使用者管理已連結的帳戶。
可變更使用者帳戶。建議使用者切換帳戶的方法。如果使用者常擁有多個帳戶，這種做法尤其實用。
- 如果使用者必須關閉同意畫面才能切換帳戶，請傳送可復原的錯誤給 Google，讓使用者以 OAuth 連結登入所需帳戶。
加入您的標誌。在同意畫面中顯示貴公司的標誌。 參考樣式規範來放置標誌。如果您也想顯示 Google 的標誌，請參閱「標誌和商標」一文。
授權碼流程
OAuth 2.0 伺服器實作授權碼流程包含兩個端點，您的服務會透過 HTTPS 提供這些端點。第一個端點是授權端點，負責尋找或取得使用者對資料存取權的同意。授權端點會向尚未登入的使用者顯示登入 UI，並記錄對要求存取權的同意聲明。第二個端點是權杖交換端點，用於取得加密字串 (稱為權杖)，授權使用者存取您的服務。
當 Google 應用程式需要呼叫您的服務 API 時，Google 會同時使用這些端點，向使用者取得授權，以便代為呼叫這些 API。
Google 啟動的 OAuth 2.0 授權碼流程工作階段具有下列流程：
- Google 會在使用者的瀏覽器中開啟授權端點。如果流程是在語音專用裝置上啟動 Action，Google 會將執行作業轉移至手機。
- 使用者會登入 (如果尚未登入)，並授權 Google 使用您的 API 存取其資料 (如果尚未授予權限)。
- 您的服務會建立授權碼並傳回給 Google。如要這樣做，請將使用者的瀏覽器重新導向至 Google，並附上請求中的授權碼。
- Google 會將授權碼傳送至您的權杖交換端點，該端點會驗證代碼的真實性，並傳回存取權杖和更新權杖。存取權杖是短期憑證，可讓服務接受憑證來存取 API。更新權杖是 Google 可儲存的長效權杖，可在存取權杖到期時取得新的存取權杖。
- 使用者完成帳戶連結流程後，Google 傳送的每項後續要求都會包含存取權存證。
處理授權要求
如需使用 OAuth 2.0 授權碼流程執行帳戶連結，Google 會將使用者傳送至授權端點，並附上包含下列參數的要求：
| 授權端點參數 | |
|---|---|
client_id |
您指派給 Google 的用戶端 ID。 |
redirect_uri |
您用來傳送回覆這項要求的網址。 |
state |
會在重新導向 URI 中傳回給 Google 的記帳值，且不會變更。 |
scope |
選用：以空格分隔的範圍字串集，用於指定 Google 要求授權的資料。 |
response_type |
回應中要傳回的值類型。對於 OAuth 2.0 授權碼流程，回應類型一律為 code。 |
user_locale |
以 RFC5646 格式呈現的 Google 帳戶語言設定，用於以使用者偏好的語言本地化內容。 |
舉例來說，如果授權端點位於 https://myservice.example.com/auth，要求可能會如下所示：
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE
如要讓授權端點處理登入要求，請按照下列步驟操作：
- 請確認
client_id與您指派給 Google 的用戶端 ID 相符，而redirect_uri與 Google 為您的服務提供的重新導向網址相符。這些檢查非常重要，可避免您將存取權授予非預期或設定錯誤的用戶端應用程式。如果您支援多個 OAuth 2.0 流程，請確認response_type為code。 - 確認使用者是否已登入服務。如果使用者未登入，請完成服務的登入或註冊流程。
- 產生授權碼，供 Google 用於存取您的 API。授權碼可以是任何字串值，但必須明確代表使用者、代碼所屬的用戶端，以及代碼的到期時間，且不得讓人輕易猜測。您通常會發出大約 10 分鐘後到期的授權碼。
- 確認
redirect_uri參數指定的網址具有下列格式：https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- 將使用者的瀏覽器重新導向至
redirect_uri參數指定的網址。透過附加code和state參數，在重新導向時加入您剛產生的授權碼和原始未修改的狀態值。以下是產生網址的範例：https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
處理權杖交換要求
您的服務權杖交換端點負責兩種權杖交換：
- 將授權碼換成存取憑證和更新憑證
- 將重新整理權杖換成存取權杖
權杖交換要求包含下列參數：
| 符記交換端點參數 | |
|---|---|
client_id |
這個字串可識別要求來源為 Google。這個字串必須在您的系統中註冊為 Google 的專屬 ID。 |
client_secret |
你向 Google 註冊的服務專用密鑰字串。 |
grant_type |
要交換的符記類型。這個值為 authorization_code 或 refresh_token。 |
code |
如果是 grant_type=authorization_code，這個參數就是 Google 從登入或符記交換端點收到的代碼。 |
redirect_uri |
如果是 grant_type=authorization_code，這個參數就是初始授權要求中使用的網址。 |
refresh_token |
如果是 grant_type=refresh_token，這個參數就是 Google 從權杖交換端點收到的更新權杖。 |
設定 Google 如何將憑證傳送至伺服器
視實作方式而定，授權伺服器會在要求主體或要求標頭中接收用戶端憑證。
根據預設，Google 會在要求主體中傳送憑證。如果授權伺服器要求用戶端憑證必須位於要求標頭中，您必須相應地設定 Cloud-to-cloud 整合：
在專案清單中，點選所需專案旁的「開啟」。
在「Cloud-to-Cloud」下方，選取「Develop」。
按一下整合項目旁的「開啟」。
向下捲動至「權限 (選用)」部分，然後選取「讓 Google 透過 HTTP 基本驗證標頭傳送用戶端 ID 和密鑰」核取方塊。
按一下「儲存」以儲存您的變更。
將授權碼換成存取憑證和更新憑證
使用者登入後，授權端點會將短期授權碼傳回給 Google，Google 會向您的憑證交換端點傳送要求，以便將授權碼交換成存取權杖和更新權杖。
對於這些要求，grant_type 的值為 authorization_code，code 的值則是您先前授予 Google 的授權碼。以下是要求範例，說明如何將授權碼換成存取權杖和更新權杖：
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI
如要將授權碼換成存取權杖和更新權杖，您的權杖交換端點會執行下列步驟，回應 POST 要求：
- 確認
client_id將要求來源識別為已授權來源，且client_secret符合預期值。 - 驗證授權碼是否有效且未過期，以及要求中指定的客戶端 ID 是否與授權碼相關聯的客戶端 ID 相符。
- 確認
redirect_uri參數指定的網址與初始授權要求中使用的值相同。 - 如果您無法驗證上述所有條件，請傳回 HTTP 400 錯誤要求錯誤，並以
{"error": "invalid_grant"}做為主體。 - 否則，請使用授權碼中的使用者 ID 產生更新權杖和存取權杖。這些權杖可以是任何字串值，但必須明確代表權杖適用的使用者和用戶端，且不得可猜測。針對存取權杖，請一併記錄權杖的到期時間，通常是在您發出權杖後一小時。更新權杖不會過期。
- 在 HTTPS 回應主體中傳回下列 JSON 物件：
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Google 會為使用者儲存存取權杖和更新權杖，並記錄存取權杖的到期日。存取權杖到期時，Google 會使用更新權杖，從憑證交換端點取得新的存取權杖。
將重新整理權杖換成存取權杖
存取權杖到期時，Google 會向您的權杖交換端點傳送要求，以便將更新權杖換成新的存取權杖。
對於這些要求，grant_type 的值為 refresh_token，而 refresh_token 的值則是您先前授予 Google 的重新整理權杖值。以下是要求範例，說明如何將重新整理權杖換成存取權杖：
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
如要將重新整理權杖換成存取權杖，您的權杖交換端點會執行下列步驟，回應 POST 要求：
- 確認
client_id將要求來源識別為 Google，且client_secret與預期值相符。 - 確認重新整理權杖有效，且要求中指定的用戶端 ID 與重新整理權杖相關聯的用戶端 ID 相符。
- 如果您無法驗證上述所有條件，請傳回 HTTP 400 錯誤要求錯誤，並以
{"error": "invalid_grant"}做為主體。 - 否則，請使用更新憑證中的使用者 ID 產生存取權杖。這些權杖可以是任何字串值，但必須明確代表權杖適用的使用者和用戶端，且不得可猜測。針對存取權存證，請一併記錄憑證的到期時間，通常是在您核發憑證後一小時。
- 在 HTTPS 回應主體中傳回下列 JSON 物件：
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
處理使用者資訊要求
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選用：使用者的個人資料相片。