OAuth 式 Google 登入「簡化」連結類型會在 OAuth 帳戶連結之上添加 Google 登入功能。這樣不僅能為 Google 使用者提供流暢的語音連結功能,還能為以非 Google 身分註冊您服務的使用者啟用帳戶連結功能。
此連結類型從「Google 登入」開始,可讓您檢查系統中是否存在使用者的 Google 個人資料資訊。如果在系統中找不到使用者資訊,則會開始標準 OAuth 流程。使用者也可以選擇使用其 Google 個人資料資訊建立新帳戶。
![](https://developers.google.cn/static/assistant/identity/images/gsi-oauth-flow.png?authuser=5&hl=zh-tw)
如要使用簡化連結類型執行帳戶連結作業,請按照下列一般步驟操作:
- 首先,請使用者同意存取自己的 Google 個人資料。
- 請使用使用者個人資料中的資訊辨識使用者。
- 如果在驗證系統中找不到與 Google 使用者相符的結果,根據您在 Actions 控制台中設定 Actions 專案,允許透過語音建立使用者帳戶,或僅能在您的網站上建立使用者帳戶,流程也會隨之繼續進行。
- 如果您允許透過語音建立帳戶,請驗證從 Google 接收的 ID 權杖。然後,您可以根據 ID 權杖中的個人資訊建立使用者。
- 如果您不允許透過語音建立帳戶,系統會將使用者轉移至瀏覽器,以便載入您的授權頁面並完成使用者建立流程。
![如果您允許透過語音建立帳戶,但在驗證系統中找不到 Google 設定檔,則必須驗證 Google 提供的 ID 權杖。然後,您可以根據 ID 權杖中的個人資訊建立使用者。如果您不允許透過語音建立使用者帳戶,系統會將使用者轉移至瀏覽器,以便載入您的授權頁面並完成流程。](https://developers.google.cn/static/assistant/identity/images/gsi-oauth-flow-creation.png?authuser=5&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 |
提供已簽署的 Google 使用者身分識別資訊的 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 帳戶是否已在驗證系統中
確認是否符合下列任一條件:
- Google 帳戶 ID (位於斷言
sub
欄位) 位於使用者資料庫中。 - 斷言中的電子郵件地址與使用者資料庫中的使用者相符。
如果其中一項條件為 true,表示使用者已經註冊,您可以發出存取權杖。
如果斷言中指定的 Google 帳戶 ID 和電子郵件地址都與資料庫中的使用者不符,表示使用者尚未註冊。在此情況下,您的憑證交換端點應以指定 error=user_not_found
的 HTTP 401 錯誤回覆,如以下範例所示:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"user_not_found", }Google 收到包含
user_not_found
錯誤的 401 錯誤回應時,會使用設為「建立」的 intent
參數值呼叫權杖交換端點,並傳送包含使用者設定檔資訊的 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。
驗證使用者資訊並建立新帳戶
確認是否符合下列任一條件:
- Google 帳戶 ID (位於斷言
sub
欄位) 位於使用者資料庫中。 - 斷言中的電子郵件地址與使用者資料庫中的使用者相符。
如果其中一項條件符合,請回應以 HTTP 401 錯誤回應要求,並將 error=linking_error
和使用者的電子郵件地址指定為 login_hint
,藉此提示使用者將現有帳戶連結至他們的 Google 帳戶,如以下範例所示:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
如果兩個條件都不成立,請使用 JWT 中提供的資訊建立新的使用者帳戶。新帳戶通常不會設定密碼。建議您將 Google 登入功能新增至其他平台,讓使用者能夠透過 Google 跨應用程式介面登入。您也可以透過電子郵件傳送啟動密碼復原流程的連結,讓使用者設定在其他平台上登入的密碼。
建立完成後,請發出存取權杖 ,並在 HTTPS 回應主體中傳回 JSON 物件的值,如以下範例所示:
{ "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 助理要求包含存取權杖,請先檢查存取權杖是否有效且尚未過期,然後從與權杖相關聯的使用者帳戶資料庫中擷取。