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

您可以讓使用者在輸入功能有限的裝置 (例如連上網路的電視) 上,使用 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,請選取「電視和受限制的輸入裝置」應用程式類型。

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

使用者要求使用 Google 帳戶登入後,您可以傳送 HTTP POST 要求至 OAuth 2.0 裝置端點 https://oauth2.googleapis.com/device/code,取得使用者代碼和驗證網址。請在要求中加入用戶端 ID 和所需的權限清單。如果您只想讓使用者透過 Google 帳戶登入,請只要求 profileemail 範圍;如果您想要求代表使用者呼叫支援的 API,請除了 profileemail 範圍外,也要求必要範圍。

以下是要求使用者代碼的範例:

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_codeverification_url 值,同時會在指定的 interval 輪詢登入端點,直到使用者登入或 expires_in 指定的時間已過為止。

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

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

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

更多資訊

  • 如要讓使用者在 ID 權杖的效期結束後仍保持登入狀態,請參閱「更新存取權杖」。
  • 如果您需要透過後端伺服器驗證,請參閱「透過後端伺服器驗證」,瞭解如何安全地進行驗證。