在電視和有限的輸入裝置上登入

您可以讓使用者在輸入受限裝置 (例如連網電視) 的裝置上，透過 Google 帳戶登入應用程式。

應用程式會向使用者顯示一組短碼和登入網址。然後，使用者在網路瀏覽器中開啟登入網址、輸入代碼，並授權應用程式存取使用者的登入資訊。最後，應用程式會收到確認通知，使用者已登入。

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

  • 裝置必須能夠顯示 40 個半形字元的網址和 15 個半形字元的使用者代碼，以及為使用者提供的操作說明。
  • 且裝置必須連上網際網路。

取得用戶端 ID 和密鑰

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

如要尋找專案的用戶端 ID 和用戶端密鑰，請按照下列步驟操作：

  1. 選取現有的 OAuth 2.0 憑證，或開啟「憑證」頁面。
  2. 如果您尚未建立專案的 OAuth 2.0 憑證，請依序點選「Create credentials」>「OAuth client ID」，然後提供建立憑證所需的資訊。
  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=YOUR_GOOGLE_CLIENT_ID&scope=email%20profile

使用 curl：

curl -d "client_id=YOUR_GOOGLE_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 登入網站會顯示類似下圖的同意畫面：

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

如果使用者按一下「Allow」(允許)，應用程式就能取得用於識別使用者的 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=YOUR_GOOGLE_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0

使用 curl：

curl -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_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(<var>id_token</var>);

// 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"];

更多資訊