OAuth 式 Google 登入「簡化」連結類型會在 OAuth 帳戶連結之上添加 Google 登入功能。這樣不僅能為 Google 使用者提供流暢的語音連結功能,還能為以非 Google 身分註冊您服務的使用者啟用帳戶連結功能。
此連結類型從「Google 登入」開始,可讓您檢查系統中是否存在使用者的 Google 個人資料資訊。如果在系統中找不到使用者資訊,則會開始標準 OAuth 流程。使用者也可以選擇使用其 Google 個人資料資訊建立新帳戶。
![](https://developers-dot-devsite-v2-prod.appspot.com/static/assistant/identity/images/gsi-oauth-flow.png?authuser=8&hl=zh-tw)
如要使用簡化連結類型執行帳戶連結作業,請按照下列一般步驟操作:
- 首先,請使用者同意存取自己的 Google 個人資料。
- 請使用使用者個人資料中的資訊辨識使用者。
- 如果在驗證系統中找不到與 Google 使用者相符的結果,根據您在 Actions 控制台中設定 Actions 專案,允許透過語音建立使用者帳戶,或僅能在您的網站上建立使用者帳戶,流程也會隨之繼續進行。
- 如果您允許透過語音建立帳戶,請驗證從 Google 接收的 ID 權杖。然後,您可以根據 ID 權杖中的個人資訊建立使用者。
- 如果您不允許透過語音建立帳戶,系統會將使用者轉移至瀏覽器,以便載入您的授權頁面並完成使用者建立流程。
![如果您允許透過語音建立帳戶,但在驗證系統中找不到 Google 設定檔,則必須驗證 Google 提供的 ID 權杖。然後,您可以根據 ID 權杖中的個人資訊建立使用者。如果您不允許透過語音建立使用者帳戶,系統會將使用者轉移至瀏覽器,以便載入您的授權頁面並完成流程。](https://developers-dot-devsite-v2-prod.appspot.com/static/assistant/identity/images/gsi-oauth-flow-creation.png?authuser=8&hl=zh-tw)
支援透過語音建立帳戶
如果您允許透過語音建立使用者帳戶,Google 助理會詢問使用者是否要執行下列操作:
- 使用孩子的 Google 帳戶資訊在系統上建立新帳戶,或
- 如果驗證系統已有 Google 以外的帳戶,請使用其他帳戶登入。
如果想要盡量減少帳戶建立流程的阻礙,建議您允許透過語音建立帳戶。使用者只有在想使用現有非 Google 帳戶登入時,才需要離開語音流程。
不允許透過語音建立帳戶
如果您禁止透過語音建立使用者帳戶,Google 助理會開啟您提供給使用者驗證的網站網址。如果互動是在沒有螢幕的裝置上進行,Google 助理會將使用者導向手機,以便繼續進行帳戶連結流程。
在下列情況下,建議您不允許建立作業:
您不希望擁有非 Google 帳戶的使用者建立新的使用者帳戶,並希望他們改為連結至驗證系統中現有的使用者帳戶。舉例來說,如果你提供會員方案,建議確保使用者不會失去現有帳戶中累積的點數。
您必須能完全掌控帳戶建立流程。例如,如果您需要在建立帳戶時向使用者顯示服務條款,則可以禁止建立。
實作 OAuth 式 Google 登入「簡易」連結
帳戶會與業界標準 OAuth 2.0 流程連結。Actions on Google 支援隱含和授權碼流程。
在隱式程式碼流程中,Google 會在使用者的瀏覽器中開啟您的授權端點。成功登入後,系統會將長期存取權杖傳回 Google。從現在起,每次透過 Google 助理傳送給您動作的要求中,都會包含這個存取權杖。
在授權碼流程中,您需要兩個端點:
- 授權端點,該端點負責將登入 UI 提供給未登入的使用者,並以簡碼授權代碼的形式,記錄使用者要求的存取權。
- 權杖交換端點,負責以下兩種交換類型:
- 交換長期更新權杖的授權碼和短期存取權杖。這項交換作業會在使用者完成帳戶連結流程時進行。
- 對短期存取權杖交換交換憑證。當 Google 需要新的存取權杖,因為更新權杖已過期時,就會發生此交換行為。
雖然隱含程式碼流程的實作方式較簡單,但 Google 建議使用隱含流程發布的存取權杖不會過期,因為若權杖與隱含流程搭配使用,就會強制使用者重新連結帳戶。如果基於安全考量而需要權杖過期,您應該考慮改用授權碼流程。
設定專案
如要將專案設為使用簡化連結,請按照下列步驟操作:
- 開啟動作主控台,然後選取要使用的專案。
- 按一下「開發」分頁標籤,然後選擇「帳戶連結」。
- 啟用「帳戶連結」旁的切換按鈕。
- 在「建立帳戶」部分中,選取「是」。
在「連結類型」中,選取「OAuth 與 Google 登入」和「隱含」。
在「客戶資訊」中執行下列操作:
- 將值指派給「Actions to Google」的用戶端 ID,即可識別來自 Google 的要求。
- 插入授權和權杖交換端點的網址。
點按「儲存」。
實作 OAuth 伺服器
為了支援 OAuth 2.0 隱含流程,您的服務會透過 HTTPS 提供授權端點。這個端點會負責驗證及取得使用者的同意聲明,取得資料存取權。授權端點代表尚未登入的使用者登入使用者介面,並記錄對於要求存取權的同意。
當您的動作需要呼叫服務的其中一個已授權 API 時,Google 會使用此端點取得使用者授權,讓他們代表他們呼叫這些 API。
Google 發起的一般 OAuth 2.0 隱含流程工作階段如下:
- Google 會在使用者的瀏覽器中開啟授權端點。如果使用者尚未登入,則請使用者登入;如果他們尚未授予權限,則授權 Google 使用您的 API 存取他們的資料。
- 您的服務會建立存取權杖,並透過將使用者的瀏覽器重新導向回 Google,使其傳回附加在要求中的存取權杖,藉此將權杖傳回 Google。
- Google 會呼叫服務的 API,並在每個要求中附加存取權杖。您的服務會驗證存取權杖是否已授予 Google 存取 API 的授權,然後完成 API 呼叫。
處理授權要求
當您的動作需要透過 OAuth 2.0 隱含流程執行帳戶連結時,Google 會透過含有下列參數的要求,將使用者導向您的授權端點:
授權端點參數 | |
---|---|
client_id |
您指派給 Google 的用戶端 ID。 |
redirect_uri |
您將回應傳送至此要求的網址。 |
state |
傳遞至 Google 的簿記值在重新導向 URI 中維持不變。 |
response_type |
回應中要傳回的值類型。若為 OAuth 2.0 隱含流程,回應類型一律為 token 。 |
舉例來說,如果您在 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
如要讓授權端點處理登入要求,請按照下列步驟操作:
驗證
client_id
和redirect_uri
值,避免將存取權授予未預期或設定錯誤的用戶端應用程式:- 確認
client_id
與您指派給 Google 的用戶端 ID 相符。 - 確認
redirect_uri
參數指定的網址形式如下:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
YOUR_PROJECT_ID 是 Actions 主控台「Project settings」(專案設定) 頁面上的 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 會透過 AppRequest,將權杖附加至後續的呼叫動作。
處理自動連結
當使用者同意您的動作存取其 Google 個人資料後,Google 傳送的要求包含已簽署的 Google 使用者身分識別資訊。 聲明包含使用者的 Google 帳戶 ID、姓名、 以及電子郵件地址為專案設定的憑證交換端點會處理
如果驗證系統中已有對應的 Google 帳戶,
權杖交換端點會傳回使用者權杖如果 Google 帳戶不是
與現有使用者相符,權杖交換端點會傳回 user_not_found
錯誤。
這項要求的格式如下:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&consent_code=CONSENT_CODE&scope=SCOPES
您的權杖交換端點必須能處理下列參數:
權杖端點參數 | |
---|---|
grant_type |
要交換的權杖類型。對於這些要求,這個
參數值為 urn:ietf:params:oauth:grant-type:jwt-bearer 。 |
intent |
這類要求的參數值為 `get`。 |
assertion |
JSON Web Token (JWT),提供已簽署 識別使用者的身分JWT 包含使用者的 Google 帳戶 ID、名稱和電子郵件地址。 |
consent_code |
選用:出現一次性代碼時,系統會發送一次性代碼, 使用者已同意您的動作存取指定範圍。 |
scope |
選用:您設定 Google 向使用者要求的範圍。 |
當權杖交換端點收到連結要求時,應執行 包括:
驗證並解碼 JWT 斷言
您可以使用適用於您語言的 JWT 解碼程式庫,驗證 JWT 斷言並解碼。 使用 Google 的公開金鑰 (適用於 JWK PEM 格式),用來驗證符記 簽章。
解碼後的 JWT 斷言會如下所示:
{ "sub": 1234567890, // The unique ID of the user's Google Account "iss": "https://accounts.google.com", // The assertion's issuer "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID "iat": 233366400, // Unix timestamp of the assertion's creation time "exp": 233370000, // Unix timestamp of the assertion's expiration time "name": "Jan Jansen", "given_name": "Jan", "family_name": "Jansen", "email": "jan@gmail.com", // If present, the user's email address "locale": "en_US" }
除了驗證權杖的簽章外,也請驗證斷言的核發機構
(iss
欄位) 為「https://accounts.google.com
」,而目標對象 (aud
欄位)
是指派給動作的用戶端 ID。
檢查驗證系統是否已有 Google 帳戶
確認是否符合下列任一條件:
- 在斷言的
sub
欄位中,Google 帳戶 ID 位於您的使用者資料庫中。 - 斷言中的電子郵件地址與您使用者資料庫中的使用者相符。
如果任一條件為 true,表示使用者已註冊,您可以核發 存取權杖
如果聲明中未提供 Google 帳戶 ID 或電子郵件地址
與您資料庫中的使用者相符,這表示對方尚未註冊。在這種情況下,您的
權杖交換端點應傳回 HTTP 401 錯誤,指定 error=user_not_found
。
如以下範例所示:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"user_not_found", }
user_not_found
錯誤的 401 錯誤回應時,
使用 intent
參數值來呼叫權杖交換端點
設為 create 並傳送包含使用者個人資訊的 ID 權杖
。
透過 Google 登入功能處理帳戶建立作業
當使用者需要在您的服務上建立帳戶時,Google 會
要求傳送至權杖交換端點
intent=create
,如以下範例所示:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&consent_code=CONSENT_CODE&assertion=JWT[&NEW_ACCOUNT_INFO]
assertion
參數包含專為您提供的 JSON Web Token (JWT) 提供的
經簽署的 Google 使用者身分識別資訊。JWT 包含
包含使用者的 Google 帳戶 ID、名稱和電子郵件地址,您可以使用
為您的服務建立新帳戶。
如要回應帳戶建立要求,您的權杖交換端點必須 包括:
驗證並解碼 JWT 斷言
您可以使用適用於您語言的 JWT 解碼程式庫,驗證 JWT 斷言並解碼。 使用 Google 的公開金鑰 (適用於 JWK PEM 格式),用來驗證符記 簽章。
解碼後的 JWT 斷言會如下所示:
{ "sub": 1234567890, // The unique ID of the user's Google Account "iss": "https://accounts.google.com", // The assertion's issuer "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID "iat": 233366400, // Unix timestamp of the assertion's creation time "exp": 233370000, // Unix timestamp of the assertion's expiration time "name": "Jan Jansen", "given_name": "Jan", "family_name": "Jansen", "email": "jan@gmail.com", // If present, the user's email address "locale": "en_US" }
除了驗證權杖的簽章外,也請驗證斷言的核發機構
(iss
欄位) 為「https://accounts.google.com
」,而目標對象 (aud
欄位)
是指派給動作的用戶端 ID。
驗證使用者資訊並建立新帳戶
確認是否符合下列任一條件:
- 在斷言的
sub
欄位中,Google 帳戶 ID 位於您的使用者資料庫中。 - 斷言中的電子郵件地址與您使用者資料庫中的使用者相符。
如果符合任一條件,請提示使用者連結現有帳戶
回應該請求,並傳回 HTTP 401 錯誤,
error=linking_error
和使用者的電子郵件地址為 login_hint
,如
範例:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
如果兩個條件皆不成立,請使用這項資訊建立新的使用者帳戶 使用這組 API新帳戶通常不會設定密碼。是 建議您在其他平台中加入 Google 登入功能,方便使用者登入 透過 Google 顯示在應用程式各平台上此外,也可以 透過電子郵件,使用可啟動密碼復原流程的連結,讓使用者完成設定 一組密碼登入其他平台
建立完畢後,請核發存取權杖 ,並傳回 JSON 物件中 也就是您的 HTTPS 回應內文,如以下範例所示:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
設計驗證流程的語音使用者介面
檢查使用者是否已通過驗證,並啟動帳戶連結流程
- 在 Actions 主控台中開啟 Actions Builder 專案。
- 建立新的場景,以便在動作中開始連結帳戶:
- 按一下「Scenes」。
- 按一下「add」圖示 (+) 即可新增場景。
- 在新建立的場景中,按一下「Conditions」(條件) 圖示 add。
- 新增條件,檢查與對話相關聯的使用者是否為已驗證的使用者。如果檢查失敗,您的動作就無法在對話期間執行帳戶連結,而是應改回提供不需要帳戶連結的功能。
- 在「Condition」(條件) 下方的
Enter new expression
欄位中,輸入下列邏輯:user.verificationStatus != "VERIFIED"
- 在「轉換」下方,選取不需要連結帳戶的場景,或不需要訪客專屬功能的進入點。
- 在「Condition」(條件) 下方的
- 按一下「條件」的「新增」圖示 add。
- 新增條件,在使用者沒有相關聯的身分時觸發帳戶連結流程。
- 在「Condition」(條件) 下方的
Enter new expression
欄位中,輸入下列邏輯:user.verificationStatus == "VERIFIED"
- 在「轉換」下方,選取「帳戶連結」系統場景。
- 點按「儲存」。
- 在「Condition」(條件) 下方的
儲存後,名為 <SceneName>_AccountLinking
的帳戶連結系統場景就會新增至專案中。
自訂帳戶連結情境
- 在「場景」下方,選取帳戶連結系統場景。
- 按一下「Send 提示」,然後新增簡短句子,說明動作需要存取其身分的原因 (例如「如要儲存偏好設定」)。
- 點按「儲存」。
- 在「條件」下方,按一下「如果使用者成功完成帳戶連結」。
- 設定使用者同意連結帳戶時,流程的後續步驟。 舉例來說,呼叫 Webhook 以處理任何所需的自訂商業邏輯,然後切換回原始場景。
- 點按「儲存」。
- 在「條件」下方,按一下「如果使用者取消或關閉帳戶連結」。
- 如果使用者不同意連結帳戶,請設定流程。例如,傳送已確認的訊息,然後重新導向至提供不需要連結帳戶的功能的場景。
- 點按「儲存」。
- 在「條件」下方,按一下「如果發生系統或網路錯誤」。
- 設定若帳戶連結流程因系統或網路錯誤而無法順利完成時,流程該如何繼續。 例如,傳送已確認的訊息,然後重新導向至提供不需要連結帳戶的功能的場景。
- 點按「儲存」。
處理資料存取要求
如果 Google 助理要求包含存取權杖,請先檢查存取權杖是否有效且尚未過期,然後從與權杖相關聯的使用者帳戶資料庫中擷取。