每個 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」。
按一下整合項目旁的「開啟」。
向下捲動至「Permissions (optional)」部分,然後選取「Have Google transmit Client ID and secret via HTTP basic auth header」核取方塊。
按一下「儲存」以儲存您的變更。
將授權碼換成存取憑證和更新憑證
使用者登入後,授權端點會將短期授權碼傳回給 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
選用:使用者的個人資料相片。