在電視和受限制的輸入裝置上登入帳戶

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

您可以允許使用者在具備有限輸入功能的裝置上 (例如已連接網路的電視) 使用自己的 Google 帳戶登入應用程式。

應用程式會向使用者顯示短碼和登入網址。接著，使用者會在網路瀏覽器中開啟登入網址並輸入代碼，並授予應用程式存取使用者的登入資訊的權限。最後，應用程式會收到確認訊息，且使用者已登入。

如要使用這個登入流程，應用程式必須在符合以下條件的裝置上執行：

  • 裝置必須能夠顯示 40 個字元的網址和 15 個字元的使用者代碼，並向使用者顯示指示。
  • 裝置必須連上網際網路。

取得用戶端 ID 和密鑰

您的應用程式需要 OAuth 2.0 用戶端 ID 和用戶端密鑰，才能向 Google 的登入端點傳送要求。

如要找出專案的用戶端 ID 和用戶端密鑰，請執行下列操作：

  1. 選取現有的 OAuth 2.0 憑證或開啟「憑證」頁面。
  2. 如果您尚未建立專案，請按一下 [Create credentials > OAuth client ID] (建立 OAuth 用戶端 ID)，然後提供建立憑證所需的資訊，藉此建立專案的 OAuth 2.0 憑證。
  3. 在「OAuth 2.0 用戶端 ID」部分找出「用戶端 ID」。 按一下用戶端 ID 即可瞭解詳情。

如果您要建立新的用戶端 ID，請選取 [TVs and Limited Input devices] (電視和有限輸入裝置) 應用程式類型。

取得使用者代碼和驗證網址

當使用者透過 Google 帳戶登入要求後，您只要將 HTTP POST 要求傳送至 OAuth 2.0 裝置端點 https://oauth2.googleapis.com/device/code，即可取得使用者代碼和驗證網址。包含您的用戶端 ID 和您需要的要求範圍範圍。如果您只想 使用其 Google 帳戶登入使用者，請只要求 profile 和 email 範圍；或者，如果您要要求以使用者的身分呼叫 支援的 API，請除了 profile 和 email 範圍之外，也要求取得所需範圍。

以下是使用者程式碼的範例：

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID&scope=email%20profile

使用 curl：

curl -d "client_id=CLIENT_ID&scope=email profile" https://oauth2.googleapis.com/device/code

回應會以 JSON 物件的形式傳回：

{
  "device_code" : "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code" : "GQVQ-JKEC",
  "verification_url" : "https://www.google.com/device",
  "expires_in" : 1800,
  "interval" : 5
}

您的應用程式會向使用者顯示 user_code 和 verification_url 值，同時以指定的 interval 輪詢登入端點，直到使用者登入或 expires_in 指定的時間已過為止。

顯示使用者代碼和驗證網址

收到裝置端點的使用者代碼和驗證網址後，請顯示這些資訊並指示使用者開啟網址並輸入使用者代碼。

verification_url 和 user_code 的值隨時可能變動。設計 UI 的方式如下：

  • 必須將 user_code 顯示在寬的欄位中，以便處理 15 個 W 大小的字元。
  • 「verification_url」必須顯示在寬的欄位中，才能處理長度為 40 個字元的網址字串。

這兩個字串可包含 US-ASCII 字元集中的任何可列印字元。

顯示 user_code 字串時，請勿以任何方式修改字串 (例如變更大小寫或插入其他格式設定字元)，因為應用程式日後如果變更程式碼的格式可能會中斷。

您可以選擇從網址中移除配置來修改 verification_url 字串，以選擇是否顯示。如果可以這麼做，請確認您的應用程式能夠處理「http」和「https」兩者的變化版本。否則請勿修改 verification_url 字串。

當使用者前往驗證網址時，會看到類似以下的頁面：

輸入代碼以連結裝置

使用者輸入使用者代碼後，Google 登入網站會顯示如下的同意畫面：

裝置用戶端的同意畫面範例

如果使用者按一下 [允許]，您的應用程式即可取得 ID 憑證以識別使用者、呼叫 Google API 的存取憑證，以及取得新憑證的重新整理憑證。

取得 ID 憑證並重新整理憑證

應用程式顯示使用者代碼和驗證網址後，請開始使用從裝置端點收到的裝置代碼來輪詢憑證端點 (https://oauth2.googleapis.com/token)。以 interval 值指定的間隔 (以秒為單位) 擷取憑證端點。

以下是要求範例：

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

client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0

使用 curl：

curl -d "client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0" https://oauth2.googleapis.com/token

如果使用者尚未核准要求，系統會如下所示：

{
  "error" : "authorization_pending"
}

您的應用程式應重複處理這些要求的頻率，且頻率不得超過 interval 的值。如果您的應用程式輪詢速度太快，回應如下：

{
  "error" : "slow_down"
}

一旦使用者登入，並授予您的應用程式存取您要求範圍的權限，應用程式對下一項要求的回應就會包含 ID 憑證、存取憑證和更新憑證：

{
  "access_token" : "ya29.AHES6ZSuY8f6WFLswSv0HZLP2J4cCvFSj-8GiZM0Pr6cgXU",
  "token_type" : "Bearer",
  "expires_in" : 3600,
  "refresh_token" : "1/551G1yXUqgkDGnkfFk6ZbjMMMDIMxo3JFc8lY8CAR-Q",
  "id_token": "eyJhbGciOiJSUzI..."
}

收到此回應後，您的應用程式可以將 ID 權杖解碼，以取得已登入使用者的基本資訊，或將 ID 憑證傳送至應用程式的後端伺服器，透過伺服器安全地進行驗證。此外，您的應用程式可以使用存取憑證來呼叫使用者授權的 Google API。

ID 和存取憑證的生命週期有限。如要讓使用者在登入憑證後繼續登入帳戶，請儲存更新憑證，並用來要求取得新憑證。

從 ID 憑證取得使用者設定檔資訊

透過任何 JWT 解碼程式庫解碼 ID 憑證，您就能取得已登入使用者的設定檔資訊。例如，使用 Auth0 jwt-decode JavaScript 程式庫：

var user_profile = jwt_decode(id_token);

// The "sub" field is available on all ID tokens. This value is unique for each
// Google account and can be used to identify the user. (But do not send this
// value to your server; instead, send the whole ID token so its authenticity
// can be verified.)
var user_id = user_profile["sub"];

// These values are available when you request the "profile" and "email" scopes.
var user_email = user_profile["email"];
var email_verified = user_profile["email_verified"];
var user_name = user_profile["name"];
var user_photo_url = user_profile["picture"];
var user_given_name = user_profile["given_name"];
var user_family_name = user_profile["family_name"];
var user_locale = user_profile["locale"];

更多資訊