OAuth 式 Google 登入「簡化」連結類型會在 OAuth 帳戶連結之上添加 Google 登入功能。這樣不僅能為 Google 使用者提供流暢的語音連結功能,還能為以非 Google 身分註冊您服務的使用者啟用帳戶連結功能。
此連結類型從「Google 登入」開始,可讓您檢查系統中是否存在使用者的 Google 個人資料資訊。如果在系統中找不到使用者資訊,則會開始標準 OAuth 流程。使用者也可以選擇使用其 Google 個人資料資訊建立新帳戶。
如要使用簡化連結類型執行帳戶連結作業,請按照下列一般步驟操作:
- 首先,請使用者同意存取自己的 Google 個人資料。
- 請使用使用者個人資料中的資訊辨識使用者。
- 如果在驗證系統中找不到與 Google 使用者相符的結果,根據您在 Actions 控制台中設定 Actions 專案,允許透過語音建立使用者帳戶,或僅能在您的網站上建立使用者帳戶,流程也會隨之繼續進行。
- 如果您允許透過語音建立帳戶,請驗證從 Google 接收的 ID 權杖。然後,您可以根據 ID 權杖中的個人資訊建立使用者。
- 如果您不允許透過語音建立帳戶,系統會將使用者轉移至瀏覽器,以便載入您的授權頁面並完成使用者建立流程。
支援透過語音建立帳戶
如果您允許透過語音建立使用者帳戶,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,將權杖附加至後續的呼叫動作。
处理自动关联
用户同意您的 Action 访问其 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 令牌 (JWT),可提供 Google 用户身份的已签名断言。JWT 包含用户的 Google 帐号 ID、名称和电子邮件地址等信息。 |
consent_code |
可选:如果存在,这是一个一次性代码,用于表明用户已同意您的 Action 访问指定范围。 |
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
字段)是否为分配给您的 Action 的客户端 ID。
检查您的身份验证系统中是否已经存在相关 Google 账号
检查是否满足以下任一条件:
- Google 帐号 ID(可在断言的
sub
字段中找到)位于您的用户数据库中。 - 断言中的电子邮件地址与用户数据库中的用户匹配。
如果满足任一条件,则表示用户已完成注册,您可以颁发访问令牌。
如果 Google 帐号 ID 和断言中指定的电子邮件地址均与您数据库中的用户不匹配,则表示该用户尚未注册。在这种情况下,您的令牌交换端点应回复 HTTP 401 错误,该错误会指定 error=user_not_found
,如以下示例所示:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"user_not_found", }当 Google 收到包含
user_not_found
错误的 401 错误响应时,Google 会调用您的令牌交换端点,将 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 网络令牌 (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
字段)是否为分配给您的 Action 的客户端 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 助理要求包含存取權杖,請先檢查存取權杖是否有效且尚未過期,然後從與權杖相關聯的使用者帳戶資料庫中擷取。