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

「OAuth 與 Google 登入」連結類型除了 OAuth 以外，還可以添加 Google 登入功能 帳戶連結。讓 Google 使用者能夠順暢使用語音連結 也可以為已註冊服務的使用者啟用帳戶連結 以非 Google 身分登入

這種連結類型開頭為 Google 登入，可讓您檢查 您的系統中已有 Google 個人資料。如果使用者資訊 在您的系統中找不到，將啟動標準 OAuth 流程。使用者也可以 選擇以 Google 個人資料建立新的帳戶。

圖 1：您的動作取得使用者的 Google 存取權後 設定檔，就可以使用這個設定檔尋找驗證系統中的使用者。

如要使用 OAuth 和 Google 登入功能進行帳戶連結，請遵循下列一般做法 步驟：

1. 請先徵得使用者同意，允許存取自己的 Google 個人資料。
2. 使用個人資料中的資訊來辨別使用者。
3. 如果在驗證系統中找不到對應的 Google 使用者， 將如何繼續流程，取決於您是否已設定 Actions 專案 以便允許使用者透過語音建立使用者帳戶 你的網站
   • 如果允許透過語音建立帳戶，請驗證身分證件 產生憑證接著，您就能根據 儲存在 ID 權杖中的設定檔資訊
   • 如果您不允許透過語音建立帳戶，系統會將使用者轉移至 瀏覽器，可在其中載入您的授權頁面並完成使用者作業 建立流程

圖 2. OAuth 和 Google 的示意圖 在系統中找不到使用者資訊時的登入流程。

支援透過語音建立帳戶

如果您允許透過語音建立使用者帳戶，Google 助理會詢問使用者是否要 他們想要採取下列行動：

• 使用他人的 Google 帳戶資訊在您的系統中建立新帳戶，或
• 使用其他帳戶登入驗證系統 現有的非 Google 帳戶。

如果您希望盡量減少透過語音建立帳戶，建議允許透過語音建立帳戶 帳戶建立流程也會更加順暢使用者只需要離開語音流程 如果他們想使用現有的非 Google 帳戶登入。

不允許透過語音建立帳戶

如果您不允許透過語音建立使用者帳戶，Google 助理會開啟 您提供給使用者驗證的網站。如果互動是發生 使用者如果裝置沒有螢幕，Google 助理會將使用者導向手機 ，繼續進行帳戶連結流程。

在下列情況下，建議您禁止建立：

• 您不想開放非 Google 帳戶的使用者建立新的 使用者帳戶，並希望他們 將他們現有的使用者帳戶連結至 驗證系統。舉例來說，假設你提供會員方案 則希望確保使用者不會失去 自己在網站上累積的點數 現有帳戶。

• 您需要完全掌控帳戶建立流程。例如，您可以 如果需要在期間內向使用者顯示服務條款，則禁止建立 建立帳戶。

，瞭解如何調查及移除這項存取權。

注意： 請選取下方其中一個流程選項，以進一步瞭解如何導入 所選的流程視需要重新載入指南內容，以配合 由您作主

允許透過語音建立帳戶 不允許透過語音建立帳戶

實作 OAuth 和 Google 登入帳戶連結

帳戶採用業界標準的 OAuth 2.0 流程連結。 Actions on Google 支援隱式和授權碼流程。

注意： 如果您要導入帳戶連結來處理財務資訊， 請注意，你的動作可能適用額外政策。最多需要六個時間 會要求我們審查「動作」中的財務資訊連結，因此 因此在規劃發布時間表時，別忘了考量這點。如何減輕審查負擔 程序，請務必遵守金融服務政策 ，再將動作送審。

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
• The token exchange endpoint, which is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

Note: Please choose which OAuth2 flow you want to implement. If needed, the content of this guide reloads to adapt to your choice.

Auth code Implicit flow

設定專案

設定專案以使用 OAuth 和 Google 登入帳戶 連結，請按照下列步驟操作：

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

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

   

6. 在「Client Information」中，執行下列操作：

   • 指派值給「Actions to Google」核發的用戶端 ID，用來識別用戶端 ID 以及來自 Google 的要求
   • 插入授權和權杖交換端點的網址。

7. 按一下 [儲存]。

實作 OAuth 伺服器

To support the OAuth 2.0 implicit flow, your service makes an authorization endpoint available by HTTPS. This endpoint is responsible for authenticating and obtaining consent from users for data access. The authorization endpoint presents a sign-in UI to your users that aren't already signed in and records consent to the requested access.

When your Action needs to call one of your service's authorized APIs, Google uses this endpoint to get permission from your users to call these APIs on their behalf.

A typical OAuth 2.0 implicit flow session initiated by Google has the following flow:

1. Google opens your authorization endpoint in the user's browser. The user signs in if not signed in already, and grants Google permission to access their data with your API if they haven't already granted permission.
2. Your service creates an access token and returns it to Google by redirecting the user's browser back to Google with the access token attached to the request.
3. Google calls your service's APIs, and attaches the access token with each request. Your service verifies that the access token grants Google authorization to access the API and then completes the API call.

Handle authorization requests

When your Action needs to perform account linking via an OAuth2 implicit flow, Google sends the user to your authorization endpoint with a request that includes the following parameters:

Authorization endpoint parameters
client_id	The client ID you assigned to Google.
redirect_uri	The URL to which you send the response to this request.
state	A bookkeeping value that is passed back to Google unchanged in the redirect URI.
response_type	The type of value to return in the response. For the OAuth 2.0 implicit flow, the response type is always token.

For example, if your authorization endpoint is available at https://myservice.example.com/auth, a request might look like:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

For your authorization endpoint to handle sign-in requests, do the following steps:

1. Verify the client_id and redirect_uri values to prevent granting access to unintended or misconfigured client apps:

   • Confirm that the client_id matches the client ID you assigned to Google.
   • Confirm that the URL specified by the redirect_uri parameter has the following form:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID is the ID found on the Project settings page of the Actions Console.

2. Check if the user is signed in to your service. If the user isn't signed in, complete your service's sign-in or sign-up flow.

3. Generate an access token that Google will use to access your API. The access token can be any string value, but it must uniquely represent the user and the client the token is for and must not be guessable.

4. Send an HTTP response that redirects the user's browser to the URL specified by the redirect_uri parameter. Include all of the following parameters in the URL fragment:

   • access_token: the access token you just generated
   • token_type: the string bearer
   • state: the unmodified state value from the original request The following is an example of the resulting URL:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google's OAuth 2.0 redirect handler will receive the access token and confirm that the state value hasn't changed. After Google has obtained an access token for your service, Google will attach the token to subsequent calls to your Action as part of the AppRequest.

Handle automatic linking

After the user gives your Action consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.

If the corresponding Google account is already present in your authentication system, your token exchange endpoint returns a token for the user. If the Google account doesn't match an existing user, your token exchange endpoint returns a user_not_found error.

The request has the following form:

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

Your token exchange endpoint must be able to handle the following parameters:

Token endpoint parameters
grant_type	The type of token being exchanged. For these requests, this parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer.
intent	For these requests, the value of this parameter is `get`.
assertion	A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
consent_code	Optional: When present, a one-time code that indicates that the user has granted consent for your Action to access the specified scopes.
scope	Optional: Any scopes you configured Google to request from users.

When your token exchange endpoint receives the linking request, it should do the following:

驗證並解碼 JWT 斷言

您可以使用適用於您語言的 JWT 解碼程式庫，驗證 JWT 斷言並解碼。 使用 Google 的公開金鑰 (適用於 JWK PEM 格式)，用來驗證符記 簽章。

注意： 金鑰不得硬式編碼，請改為按照 OpenID 連線探索操作 通訊協定 ，然後檢查 cache-control 標頭，決定金鑰的快取時間長度。

解碼後的 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": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

除了驗證權杖的簽章外，也請驗證斷言的核發機構 (iss 欄位) 為「https://accounts.google.com」，而目標對象 (aud 欄位) 是指派給動作的用戶端 ID。

Check if the Google account is already present in your authentication system

Check whether either of the following conditions are true:

• The Google Account ID, found in the assertion's sub field, is in your user database.
• The email address in the assertion matches a user in your user database.

If either condition is true, the user has already signed up and you can issue an access token.

If neither the Google Account ID nor the email address specified in the assertion matches a user in your database, the user hasn't signed up yet. In this case, your token exchange endpoint should reply with a HTTP 401 error, that specifies error=user_not_found, as in the following example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"user_not_found",
}

When Google receives the 401 error response with a user_not_found error, Google calls your token exchange endpoint with the value of the intent parameter set to create and sending an ID token that contains the user's profile information with the request.

Handle account creation via Google Sign-In

When a user needs to create an account on your service, Google makes a request to your token exchange endpoint that specifies intent=create, as in the following example:

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]

The assertion parameter contains A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address, which you can use to create a new account on your service.

To respond to account creation requests, your token exchange endpoint must do the following:

驗證並解碼 JWT 斷言

您可以使用適用於您語言的 JWT 解碼程式庫，驗證 JWT 斷言並解碼。 使用 Google 的公開金鑰 (適用於 JWK PEM 格式)，用來驗證符記 簽章。

注意： 金鑰不得硬式編碼，請改為按照 OpenID 連線探索操作 通訊協定 ，然後檢查 cache-control 標頭，決定金鑰的快取時間長度。

解碼後的 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": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

除了驗證權杖的簽章外，也請驗證斷言的核發機構 (iss 欄位) 為「https://accounts.google.com」，而目標對象 (aud 欄位) 是指派給動作的用戶端 ID。

Validate user information and create new account

Check whether either of the following conditions are true:

• The Google Account ID, found in the assertion's sub field, is in your user database.
• The email address in the assertion matches a user in your user database.

If either condition is true, prompt the user to link their existing account with their Google Account by responding to the request with an HTTP 401 error, specifying error=linking_error and the user's email address as the login_hint, as in the following example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"[e-mail]"
}

If neither condition is true, create a new user account using the information provided in the JWT. New accounts do not typically have a password set. It is recommended that you add Google Sign In to other platforms to enable users to log in via Google across the surfaces of your application. Alternatively, you can email the user a link that starts your password recovery flow to allow the user to set a password for signing in on other platforms.

When the creation is completed, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  
  "expires_in": SECONDS_TO_EXPIRATION
}

啟動驗證流程

警告：請勿為使用者提供必要帳戶 連結提示。 為未經驗證的使用者提供訪客流程，讓他們瞭解動作的運作方式。 只在必要時才要求帳戶連結如果使用者是 由於帳戶連結發生問題，而持續離開「動作」這項動作，Google 會 未積極宣傳該動作，可能導致「動作」的使用者流量減少。

請注意，只有通過驗證的使用者才能連結帳戶。如果使用者是 訪客和帳戶連結將會失敗瞭解識別及處理方式 訪客使用者。

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

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 助理要求包含存取權杖， 請先檢查存取權杖是否有效且尚未過期，然後再從 使用者帳戶資料庫。