您可以讓用戶在輸入功能有限的設備(例如聯網電視)上使用他們的 Google 帳戶登錄您的應用。
該應用程序向用戶顯示一個短代碼和登錄 URL。然後,用戶在 Web 瀏覽器中打開登錄 URL,輸入代碼,並授予應用訪問用戶登錄信息的權限。最後,應用程序收到確認並且用戶登錄。
要使用此登錄流程,應用程序必須在滿足以下條件的設備上運行:
- 設備必須能夠顯示 40 個字符的 URL 和 15 個字符的用戶代碼,以及對用戶的說明。
- 設備必須連接到 Internet。
獲取客戶端 ID 和客戶端密碼
您的應用需要 OAuth 2.0 客戶端 ID 和客戶端密碼才能向 Google 的登錄端點發出請求。
要查找項目的客戶端 ID 和客戶端密碼,請執行以下操作:
- 選擇現有的 OAuth 2.0 憑證或打開憑證頁面。
- 如果您還沒有這樣做,請單擊Create credentials > OAuth client ID 創建項目的 OAuth 2.0 憑證,並提供創建憑證所需的信息。
- 在OAuth 2.0 客戶端 ID部分中查找客戶端 ID。有關詳細信息,請單擊客戶端 ID。
如果您要創建新的客戶端 ID,請選擇電視和受限輸入設備應用程序類型。
獲取用戶代碼和驗證 URL
用戶請求使用 Google 帳戶登錄後,您可以通過向 OAuth 2.0 設備端點https://oauth2.googleapis.com/device/code
發送 HTTP POST 請求來獲取用戶代碼和驗證 URL。在請求中包含您的客戶端 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
指定的時間過去。
顯示用戶代碼和驗證 URL
從設備端點收到用戶代碼和驗證 URL 後,顯示它們並指示用戶打開 URL 並輸入用戶代碼。
user_code
verification_url
值可能會發生變化。以可以處理以下限制的方式設計您的 UI:
-
user_code
必須顯示在足以處理 15 個W
大小字符的字段中。 -
verification_url
必須顯示在足以處理 40 個字符長的 URL 字符串的字段中。
兩個字符串都可以包含 US-ASCII 字符集中的任何可打印字符。
當您顯示user_code
字符串時,請不要以任何方式修改字符串(例如更改大小寫或插入其他格式字符),因為如果將來代碼格式發生更改,您的應用程序可能會中斷。
如果您願意,您可以通過從 URL 中剝離方案來修改verification_url
字符串以進行顯示。如果這樣做,請確保您的應用程序可以同時處理“http”和“https”變體。不要以其他方式修改verification_url
字符串。
當用戶導航到驗證 URL 時,他們會看到類似於以下內容的頁面:
用戶輸入用戶代碼後,Google 登錄站點會顯示類似於以下內容的同意屏幕:
如果用戶單擊Allow ,那麼您的應用可以獲取一個 ID 令牌來識別用戶,一個訪問令牌來調用 Google API,以及一個刷新令牌來獲取新令牌。
獲取 ID 令牌和刷新令牌
在您的應用顯示用戶代碼和驗證 URL 後,開始使用您從設備端點收到的設備代碼輪詢令牌端點 ( 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"];
更多信息
- 要使用戶在 ID 令牌的生命週期後仍保持登錄狀態,請參閱刷新訪問令牌。
- 如果您需要使用後端服務器進行身份驗證,請參閱使用後端服務器進行身份驗證以獲取有關安全執行此操作的信息。