每個 smart home 動作都必須包含 驗證使用者
驗證功能可讓您將使用者Google 帳戶 建立電子郵件地址這有助於在 你的執行要求收到智慧型住宅意圖。Google 智慧型住宅僅支援使用 授權碼流程
本頁說明如何設定 OAuth 2.0 伺服器，以便與 您的 smart home 動作。
使用 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 提供第一個端點 是授權端點，負責尋找或取得 徵得使用者同意並授予資料存取權授權端點會顯示 登入使用者介面，供尚未登入的使用者查看，且將同意 所要求的存取權第二個端點是權杖交換端點 用於取得加密字串 (稱為「權杖」)，藉此授權使用者 存取您的服務。
當 Google 應用程式需要呼叫服務的其中一個 API 時，Google 會使用 這些端點都會一起取得權限，以便使用者呼叫這些 API 管理。
由 Google 發起的 OAuth 2.0 授權碼流程工作階段， 下列流程：
- Google 會在使用者的瀏覽器中開啟授權端點。如果流程 透過純語音裝置啟動動作，則 Google 將 到手機上
- 使用者登入後 (如果尚未登入)，並將權限授予 Google 透過您的 API 存取他們的資料 (如果尚未授予權限)。
- 您的服務會建立授權碼，並傳回 Google。待辦 因此，請透過授權碼將使用者的瀏覽器重新導向回 Google 附加在要求中
- Google 將授權碼傳送至權杖交換端點 驗證程式碼的真實性，並傳回存取權杖和 更新權杖。存取權杖是服務 以憑證存取 API。更新權杖存在長期 憑證，可供 Google 儲存，用於取得新的存取權杖 過期。
- 使用者完成帳戶連結流程後， 來自 Google 的要求會包含存取權杖。
處理授權要求
使用 OAuth 2.0 授權碼執行帳戶連結時 流程時，Google 會透過以下要求將使用者傳送到您的授權端點 包含下列參數：
| 授權端點參數 | |
|---|---|
client_id |
您指派給 Google 的用戶端 ID。 |
redirect_uri |
您傳送回應到這項要求的網址。 |
state |
傳回給 Google 的記帳金額，值維持不變 重新導向 URI |
scope |
選用：一組以空格分隔的範圍字串，指定 也就是 Google 要求授權的資料 |
response_type |
要在回應中傳回的值類型。針對 OAuth 2.0
授權碼流程，回應類型一律為 code。
|
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&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 專屬識別碼。 |
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 會向你的權杖交換要求傳送要求 來交換存取權杖的授權碼 產生下一個符記
在這些要求中，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 與 授權碼。
- 確認
redirect_uri參數指定的網址相同 設為初始授權要求使用的值。 - 如果您無法驗證上述所有條件，請傳回 HTTP
400 「Bad Request」錯誤，內文為
{"error": "invalid_grant"}。 - 否則，請使用授權碼中的使用者 ID 產生重新整理 權杖和存取權杖這些符記可以是任何字串值，但 必須明確代表憑證所屬的用戶端、 另一個使用者如果是存取權杖，也請記下 權杖，通常是在您核發權杖後 1 小時。 重新整理權杖沒有期限。
- 在 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 相符。
- 如果您無法驗證上述所有條件，請傳回 HTTP 400
「Bad Request」錯誤，以
{"error": "invalid_grant"}為主體。 - 否則，請使用更新權杖的使用者 ID 產生存取權 產生下一個符記這些權杖可以是任何字串值，但必須不重複 代表使用者和用戶端，不得 容易猜測的字詞如果是存取權杖，也請記錄權杖的到期時間 通常在核發權杖後一小時。
- 在 HTTPS 內文中傳回下列 JSON 物件
回應：
{ "token_type": "熊", "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選用：使用者的個人資料相片。