Overview

Every smart home Action must include a mechanism for authenticating users.

Authentication allows you to link your users' Google accounts with user accounts in your authentication system. This allows you to identify your users when your fulfillment receives a smart home intent. Google smart home only supports OAuth with an authorization code flow.

設計準則

本節介紹“ App Flip帳戶鏈接同意”屏幕的設計要求和建議。 Google調用您的應用程序後,您的應用程序會向用戶顯示同意屏幕。

要求

  1. 您必須告知用戶帳戶已鏈接到Google,而不是特定的Google產品(例如Google Home或Google Assistant)。

推薦建議

我們建議您執行以下操作:

  1. 顯示Google的隱私權政策。在同意屏幕上包括指向Google隱私權政策的鏈接。

  2. 要共享的數據。使用簡潔明了的語言告訴用戶Google需要提供哪些數據以及原因。

  3. 清除號召性用語。在您的同意屏幕上註明明確的號召性用語,例如“同意並鏈接”。這是因為用戶需要了解與Google共享帳戶鏈接所需的數據。

  4. 取消的能力。如果用戶選擇不鏈接,則為用戶提供返回或取消的方式。

  5. 取消鏈接的能力。為用戶提供取消鏈接的機制,例如指向其平台上的帳戶設置的URL。或者,您可以包含指向Google帳戶的鏈接,用戶可以在其中管理其鏈接的帳戶。

  6. 能夠更改用戶帳戶。建議用戶切換帳戶的方法。如果用戶傾向於擁有多個帳戶,這將特別有益。

    • 如果用戶必須關閉同意屏幕才能切換帳戶,請向Google發送一個可恢復的錯誤,以便該用戶可以使用OAuth鏈接隱式流程登錄所需的帳戶。
  7. 包括您的徽標。在同意屏幕上顯示您的公司徽標。使用樣式準則放置徽標。如果您還希望顯示Google的徽標,請參閱徽標和商標

此圖顯示了示例同意屏幕,其中包含設計用戶同意屏幕時要遵循的各個要求和建議的信息。
圖2.帳戶鏈接同意屏幕設計指南。

Implement OAuth account linking

To implement OAuth account linking in your smart home Action, you must do the following:

  1. Implement your OAuth 2.0 server.
  2. Configure account linking in the Actions console.

Implement your OAuth 2.0 server

This section describes how to set up your OAuth 2.0 server so that it works with your smart home Action.

授權代碼流的OAuth 2.0服務器實現由兩個端點組成,您的服務可通過HTTPS來使用這兩個端點。第一個端點是授權端點,它負責查找用戶或獲取用戶的數據訪問同意。授權端點向尚未登錄的用戶顯示登錄UI,並記錄對請求訪問的同意。第二個端點是令牌交換端點,用於獲取授權用戶訪問您的服務的加密字符串(稱為令牌)。

當Google應用程序需要調用您的服務的API之一時,Google會一起使用這些端點來獲得用戶的許可,以代表他們調用這些API。

Google發起的OAuth 2.0授權代碼流程會話具有以下流程:

  1. Google在用戶的瀏覽器中打開您的授權端點。如果該流程是在操作的僅語音設備上啟動的,則Google會將執行轉移到手機上。
  2. 該用戶登錄(如果尚未登錄),如果尚未授予Google許可,則可以使用您的API來訪問其數據。
  3. 您的服務將創建一個授權碼,並將其返回給Google。為此,請將用戶的瀏覽器重定向到Google,並在請求中附加授權碼。
  4. Google將授權代碼發送到您的令牌交換端點,該端點會驗證代碼的真實性並返回訪問令牌刷新令牌。訪問令牌是您的服務接受作為訪問API的憑據的短暫令牌。刷新令牌是一個長期存在的令牌,Google可以存儲該令牌並使用該令牌在新的訪問令牌到期時獲取這些令牌。
  5. 用戶完成帳戶鏈接流程後,從Google發送的每個後續請求都包含一個訪問令牌。

處理授權請求

當您需要使用OAuth 2.0授權代碼流執行帳戶鏈接時,Google會通過包含以下參數的請求將用戶發送到您的授權端點:

授權端點參數
client_id您在Google註冊的Google客戶ID。
redirect_uri您將對此請求的響應發送到的URL。
state重定向URI中的傳遞給Google的簿記值保持不變。
scope可選:一組用空格分隔的範圍字符串,用於指定Google正在請求其授權的數據。
response_type要在響應中返回的值的類型。對於OAuth 2.0授權代碼流,響應類型始終為code
user_locale RFC5646格式的Google帳戶語言設置,用於以用戶首選的語言本地化您的內容。

例如,如果您的授權端點位於https://myservice.example.com/auth ,則請求可能類似於以下內容:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

為了使您的授權端點能夠處理登錄請求,請執行以下步驟:

  1. 驗證client_id與您在Google中註冊的Google客戶ID匹配,並且redirect_uri與Google為您提供的服務的重定向URL匹配。這些檢查對於防止授予對意外或錯誤配置的客戶端應用程序訪問很重要。如果您支持多個OAuth 2.0流,還請確認response_typecode
  2. 檢查用戶是否登錄到您的服務。如果用戶未登錄,請完成服務的登錄或註冊流程。
  3. 生成供Google訪問您的API的授權碼。授權代碼可以是任何字符串值,但是它必須唯一地代表用戶,令牌所針對的客戶端以及代碼的到期時間,並且不能讓人猜測。通常,您發出的授權碼將在大約10分鐘後過期。
  4. 確認redirect_uri參數指定的URL具有以下格式:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  5. 將用戶的瀏覽器重定向到redirect_uri參數指定的URL。通過附加codestate參數進行重定向時,請包括剛生成的授權代碼以及未經修改的原始狀態值。以下是所得URL的示例:
    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

處理令牌交換請求

服務的令牌交換端點負責兩種令牌交換:

  • 交換訪問令牌和刷新令牌的授權代碼
  • 將刷新令牌交換為訪問令牌

令牌交換請求包括以下參數:

令牌交換端點參數
client_id一個字符串,用於將請求來源標識為Google。此字符串必須在您的系統中註冊為Google的唯一標識符。
client_secret您在Google註冊的用於服務的秘密字符串。
grant_type交換令牌的類型。它是authorization_coderefresh_token
codegrant_type=authorization_code ,此參數是Google從您的登錄或令牌交換端點接收到的代碼。
redirect_urigrant_type=authorization_code ,此參數是初始授權請求中使用的URL。
refresh_tokengrant_type=refresh_token ,此參數是Google從令牌交換端點收到的刷新令牌。
交換訪問令牌和刷新令牌的授權代碼

用戶登錄後,您的授權端點將短暫的授權碼返回給Google,Google會向您的令牌交換端點發送請求,以將授權碼交換為訪問令牌和刷新令牌。

對於這些請求, grant_type的值是authorization_code ,而code的值是您之前授予Google的授權碼的值。以下是請求交換訪問令牌和刷新令牌的授權碼的示例:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

要交換訪問令牌和刷新令牌的授權代碼,令牌交換端點通過執行以下步驟來響應POST請求:

  1. 驗證client_id將請求來源標識為授權來源,並且client_secret與期望值匹配。
  2. 驗證授權碼是否有效且未過期,以及請求中指定的客戶端ID是否與與授權碼關聯的客戶端ID匹配。
  3. 確認redirect_uri參數指定的URL與初始授權請求中使用的值相同。
  4. 如果無法驗證以上所有條件,請返回HTTP 400錯誤請求錯誤,並以{"error": "invalid_grant"}作為正文。
  5. 否則,使用授權碼中的用戶ID生成刷新令牌和訪問令牌。這些標記可以是任何字符串值,但是它們必須唯一地代表該標記所針對的用戶和客戶端,並且它們不可猜測。對於訪問令牌,還記錄令牌的到期時間,通常是您發行令牌後的一個小時。刷新令牌不會過期。
  6. 在HTTPS響應的主體中返回以下JSON對象:
    {
    "token_type": "Bearer",
    "access_token": "ACCESS_TOKEN",
    "refresh_token": "REFRESH_TOKEN",
    "expires_in": SECONDS_TO_EXPIRATION
    }
    

Google為用戶存儲訪問令牌和刷新令牌,並記錄訪問令牌的到期時間。訪問令牌過期後,Google會使用刷新令牌從您的令牌交換端點獲取新的訪問令牌。

將刷新令牌交換為訪問令牌

訪問令牌過期後,Google會向您的令牌交換端點發送請求,以將刷新令牌交換為新的訪問令牌。

對於這些請求, grant_type的值是refresh_token ,而refresh_token的值是您之前授予Google的刷新令牌的值。以下是將刷新令牌交換為訪問令牌的請求的示例:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

要將刷新令牌交換為訪問令牌,令牌交換端點將通過執行以下步驟來響應POST請求:

  1. 驗證client_id將請求來源標識為Google,並且client_secret與期望值匹配。
  2. 驗證刷新令牌是否有效,以及請求中指定的客戶端ID是否與與刷新令牌關聯的客戶端ID匹配。
  3. 如果您無法驗證所有上述條件,請返回HTTP 400錯誤請求錯誤,並以{"error": "invalid_grant"}作為正文。
  4. 否則,請使用刷新令牌中的用戶ID生成訪問令牌。這些標記可以是任何字符串值,但是它們必須唯一地代表該標記所針對的用戶和客戶端,並且它們不可猜測。對於訪問令牌,還記錄令牌的到期時間,通常是在您發行令牌後的一個小時內。
  5. 在HTTPS響應的主體中返回以下JSON對象:
    {
    "token_type": "Bearer",
    "access_token": " ACCESS_TOKEN ",
    "expires_in": SECONDS_TO_EXPIRATION
    }

Configure account linking in the console

To set up account linking in the Actions console, follow these steps:

  1. Go to the Actions console.
  2. Select your smart home Action project.
  3. Click the Develop tab. Then, click Account linking in the left navigation.
  4. Fill out all the fields under OAuth Client information. Click Next.
  5. Click Save.

Next steps (optional)

Once you have an OAuth 2.0 implementation, you can optionally configure OAuth-based App Flip, which allows your users to more quickly link their accounts in your authentication system to their Google accounts. For App Flip implementation instructions, see OAuth-based App Flip.