您可以允许用户在输入功能有限的设备上(例如联网电视)使用其 Google 帐号登录您的应用。
应用会向用户显示短代码和登录网址。然后,用户在网络浏览器中打开登录网址,输入验证码,并向应用授予访问用户登录信息的权限。最后,应用会收到确认消息,并且用户已登录。
如需使用此登录流程,应用必须在符合以下条件的设备上运行:
- 设备必须能够显示包含 40 个字符的网址和 15 个字符的用户代码,以及向用户显示的说明。
- 设备必须连接到互联网。
获取客户端 ID 和客户端密钥
您的应用需要 OAuth 2.0 客户端 ID 和客户端密钥才能向 Google 的登录端点发出请求。
如需查找项目的客户端 ID 和客户端密钥,请执行以下操作:
- 选择现有的 OAuth 2.0 凭据或打开“凭据”页面。
- 如果您尚未创建项目的 OAuth 2.0 凭据,请先点击创建凭据 > OAuth 客户端 ID 并提供创建凭据所需的信息(如果您尚未执行此操作)。
- 在 OAuth 2.0 客户端 ID 部分查找客户端 ID。如需了解详情,请点击客户端 ID。
如果您要创建新的客户端 ID,请选择 TV 和受限输入设备应用类型。
获取用户代码和验证网址
在用户请求使用 Google 帐号登录后,您需要通过向 OAuth 2.0 设备端点 https://oauth2.googleapis.com/device/code
发送 HTTP POST 请求来获取用户代码和验证网址。将您的客户端 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
的值随时可能更改。请设计可处理以下限制的界面:
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"];
详细信息
- 要在 ID 令牌的生命周期内保持登录状态,请参阅刷新访问令牌。
- 如果您需要使用后端服务器进行身份验证,请参阅使用后端服务器进行身份验证,了解如何安全地进行身份验证。