透過 OAuth 和 Google 登入 (Dialogflow) 連結帳戶

OAuth 與 Google 登入連結類型除了 OAuth 帳戶連結之外,還會新增 Google 登入。這項功能可為 Google 使用者提供流暢的語音連結功能,同時也能為以非 Google 身分註冊您服務的使用者啟用帳戶連結功能。

此連結類型從「Google 登入」開始,可讓您檢查系統中是否存在使用者的 Google 個人資料資訊。如果在系統中找不到使用者資訊,則會開始標準 OAuth 流程。使用者也可以選擇使用其 Google 個人資料資訊建立新帳戶。

圖 1:動作獲得使用者的 Google 個人資料存取權後,您就能使用動作在驗證系統中尋找相符的使用者。

如要透過 OAuth 和 Google 登入執行帳戶連結,請按照下列一般步驟操作:

  1. 首先,請使用者同意存取自己的 Google 個人資料。
  2. 請使用使用者個人資料中的資訊辨識使用者。
  3. 如果在驗證系統中找不到與 Google 使用者相符的結果,根據您在 Actions 控制台中設定 Actions 專案,允許透過語音建立使用者帳戶,或僅能在您的網站上建立使用者帳戶,流程也會隨之繼續進行。
    • 如果您允許透過語音建立帳戶,請驗證從 Google 接收的 ID 權杖。然後,您可以根據 ID 權杖中的個人資訊建立使用者。
    • 如果您不允許透過語音建立帳戶,系統會將使用者轉移至瀏覽器,以便載入您的授權頁面並完成使用者建立流程。
如果您允許透過語音建立帳戶,但在驗證系統中找不到 Google 設定檔,則必須驗證 Google 提供的 ID 權杖。然後,您可以根據 ID 權杖中的個人資訊建立使用者。如果您不允許透過語音建立使用者帳戶,系統會將使用者轉移至瀏覽器,以便載入您的授權頁面並完成流程。
圖 2. 在系統中找不到使用者資訊時的 OAuth 和 Google 登入流程示意圖。

支援透過語音建立帳戶

如果您允許透過語音建立使用者帳戶,Google 助理會詢問使用者是否要執行下列操作:

  • 使用孩子的 Google 帳戶資訊在系統上建立新帳戶,或
  • 如果驗證系統已有 Google 以外的帳戶,請使用其他帳戶登入。

如果想要盡量減少帳戶建立流程的阻礙,建議您允許透過語音建立帳戶。使用者只有在想使用現有非 Google 帳戶登入時,才需要離開語音流程。

不允許透過語音建立帳戶

如果您禁止透過語音建立使用者帳戶,Google 助理會開啟您提供給使用者驗證的網站網址。如果互動是在沒有螢幕的裝置上進行,Google 助理會將使用者導向手機,以便繼續進行帳戶連結流程。

在下列情況下,建議您不允許建立作業:

  • 您不希望擁有非 Google 帳戶的使用者建立新的使用者帳戶,並希望他們改為連結至驗證系統中現有的使用者帳戶。舉例來說,如果你提供會員方案,建議確保使用者不會失去現有帳戶中累積的點數。

  • 您必須能完全掌控帳戶建立流程。例如,如果您需要在建立帳戶時向使用者顯示服務條款,則可以禁止建立。

實作 OAuth 和 Google 登入帳戶連結

帳戶會與業界標準 OAuth 2.0 流程連結。Actions on Google 支援隱含和授權碼流程。

在隱式程式碼流程中,Google 會在使用者的瀏覽器中開啟您的授權端點。成功登入後,系統會將長期存取權杖傳回 Google。從現在起,每次透過 Google 助理傳送給您動作的要求中,都會包含這個存取權杖。

在授權碼流程中,您需要兩個端點:

  • 授權端點,該端點負責將登入 UI 提供給未登入的使用者,並以簡碼授權代碼的形式,記錄使用者要求的存取權。
  • 權杖交換端點,負責以下兩種交換類型:
    1. 交換長期更新權杖的授權碼和短期存取權杖。這項交換作業會在使用者完成帳戶連結流程時進行。
    2. 對短期存取權杖交換交換憑證。當 Google 需要新的存取權杖,因為更新權杖已過期時,就會發生此交換行為。

雖然隱含程式碼流程的實作方式較簡單,但 Google 建議使用隱含流程發布的存取權杖不會過期,因為若權杖與隱含流程搭配使用,就會強制使用者重新連結帳戶。如果基於安全考量而需要權杖過期,您應該考慮改用授權碼流程。

設定專案

如要將專案設定為使用 OAuth 和 Google 登入帳戶連結,請按照下列步驟操作:

  1. 開啟動作主控台,然後選取要使用的專案。
  2. 按一下「開發」分頁標籤,然後選擇「帳戶連結」
  3. 啟用「帳戶連結」旁的切換按鈕。
  4. 在「建立帳戶」部分中,選取「是」

  5. 在「連結類型」中,選取「OAuth 與 Google 登入」和「隱含」

  6. 在「客戶資訊」中執行下列操作:

    • 將值指派給「Actions to Google」的用戶端 ID,即可識別來自 Google 的要求。
    • 插入授權和權杖交換端點的網址。
  7. 點按「儲存」

實作 OAuth 伺服器

為了支援 OAuth 2.0 隱含流程,您的服務會透過 HTTPS 提供授權端點。這個端點會負責驗證及取得使用者的同意聲明,取得資料存取權。授權端點代表尚未登入的使用者登入使用者介面,並記錄對於要求存取權的同意。

當您的動作需要呼叫服務的其中一個已授權 API 時,Google 會使用此端點取得使用者授權,讓他們代表他們呼叫這些 API。

Google 發起的一般 OAuth 2.0 隱含流程工作階段如下:

  1. Google 會在使用者的瀏覽器中開啟授權端點。如果使用者尚未登入,則請使用者登入;如果他們尚未授予權限,則授權 Google 使用您的 API 存取他們的資料。
  2. 您的服務會建立存取權杖,並透過將使用者的瀏覽器重新導向回 Google,使其傳回附加在要求中的存取權杖,藉此將權杖傳回 Google。
  3. Google 會呼叫服務的 API,並在每個要求中附加存取權杖。您的服務會驗證存取權杖是否已授予 Google 存取 API 的授權,然後完成 API 呼叫。

處理授權要求

當您的動作需要透過 OAuth2 隱含流程執行帳戶連結時,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

如要讓授權端點處理登入要求,請按照下列步驟操作:

  1. 驗證 client_idredirect_uri 值,避免將存取權授予未預期或設定錯誤的用戶端應用程式:

    • 確認 client_id 與您指派給 Google 的用戶端 ID 相符。
    • 確認 redirect_uri 參數指定的網址形式如下:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      YOUR_PROJECT_ID 是 Actions 主控台「Project settings」(專案設定) 頁面上的 ID。
  2. 檢查使用者是否已登入您的服務。如果使用者尚未登入,請完成服務的登入或註冊流程。

  3. 產生 Google 用來存取 API 的存取權杖。存取權杖可以是任何字串值,但權杖必須專門代表使用者和用戶端,且不得猜測。

  4. 傳送 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 的公開金鑰 (JWKPEM 格式) 驗證權杖的簽名。

解碼時,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 的公開金鑰 (JWKPEM 格式) 驗證權杖的簽名。

解碼時,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
}

啟動驗證流程

使用帳戶登入輔助程式意圖啟動驗證流程。

Dialogflow (Node.js)
const app = dialogflow({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
})

// Intent that starts the account linking flow.
app.intent('Start Signin', conv => {
  conv.ask(new SignIn('To get your account details'))
})

Dialogflow (Java)
private String clientId = "<your_client_id>";

@ForIntent("Start Signin")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}
Actions SDK (Node.js)
const app = actionssdk({
  clientId: CLIENT_ID,
})

app.intent('Start Signin', conv => {
  conv.ask(new SignIn('To get your account details'))
})

Actions SDK (Java)
private String clientId = "<your_client_id>";

@ForIntent("actions.intent.TEXT")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

處理資料存取要求

如果 Google 助理要求包含存取權杖,請先檢查存取權杖是否有效且尚未過期,然後從與權杖相關聯的使用者帳戶資料庫中擷取。