警告:这些数据是根据 Google 用户数据政策提供的。请查看并遵守该政策。否则,可能会导致项目或帐号被暂停。

在电视和受限输入设备上登录

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

您可以允许用户在输入功能有限的设备上(例如联网电视)使用其 Google 帐号登录您的应用。

应用会向用户显示短代码和登录网址。然后,用户在网络浏览器中打开登录网址,输入验证码,并向应用授予访问用户登录信息的权限。最后,应用会收到确认消息,并且用户已登录。

如需使用此登录流程,应用必须在符合以下条件的设备上运行:

  • 设备必须能够显示包含 40 个字符的网址和 15 个字符的用户代码,以及向用户显示的说明。
  • 设备必须连接到互联网。

获取客户端 ID 和客户端密钥

您的应用需要 OAuth 2.0 客户端 ID 和客户端密钥才能向 Google 的登录端点发出请求。

如需查找项目的客户端 ID 和客户端密钥,请执行以下操作:

  1. 选择现有的 OAuth 2.0 凭据或打开“凭据”页面
  2. 如果您尚未创建项目的 OAuth 2.0 凭据,请先点击创建凭据 > OAuth 客户端 ID 并提供创建凭据所需的信息(如果您尚未执行此操作)。
  3. OAuth 2.0 客户端 ID 部分查找客户端 ID。如需了解详情,请点击客户端 ID。

如果您要创建新的客户端 ID,请选择 TV 和受限输入设备应用类型。

获取用户代码和验证网址

在用户请求使用 Google 帐号登录后,您需要通过向 OAuth 2.0 设备端点 https://oauth2.googleapis.com/device/code 发送 HTTP POST 请求来获取用户代码和验证网址。将您的客户端 ID 和请求范围列表包含在请求中。如果您只想让用户使用其 Google 帐号登录,请仅请求 profileemail 范围;或者,如果您想请求代表用户调用受支持的 API,那么除了 profileemail 范围之外,还应请求所需的范围。

以下是用户代码的请求示例:

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_codeverification_url 值,并同时在指定的 interval 上轮询登录端点,直到用户登录或 expires_in 指定的时间已过。

显示用户代码和验证网址

从设备端点收到用户代码和验证网址后,显示这些代码并指示用户打开网址并输入用户代码。

verification_urluser_code 的值随时可能更改。请设计可处理以下限制的界面:

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

详细信息