网络身份验证协议利用 HTTP 功能,但 Chrome 应用在应用容器内运行;它们不会通过 HTTP 加载,也无法执行重定向或设置 Cookie。
使用 Chrome Identity API 对用户进行身份验证:getAuthToken
表示登录其 Google 帐号的用户,launchWebAuthFlow
表示登录非 Google 帐号的用户。如果您的应用使用自己的服务器对用户进行身份验证,则您需要使用后者。
运作方式
Chrome 应用用户拥有与其个人资料关联的 Google 帐号。应用可以使用 getAuthToken
API 为这些用户获取 OAuth2 令牌。
想要通过非 Google 身份提供方进行身份验证的应用必须调用 launchWebAuthFlow
。此方法使用浏览器弹出式窗口来显示提供程序页面,并捕获指向特定网址格式的重定向。系统会将重定向网址传递给应用,然后应用会从网址中提取令牌。
Google 账号身份验证
以下是您需要完成的五个步骤:
- 向清单中添加权限,然后上传应用。
- 将已安装的
manifest.json
中的密钥复制到您的源清单中,以便您的应用 ID 在开发过程中保持不变。 - 为您的 Chrome 应用获取 OAuth2 客户端 ID。
- 请更新您的清单,在其中添加客户端 ID 和范围。
- 获取身份验证令牌。
添加权限和上传应用
您需要确保在您的清单中包含身份权限。然后,您就可以将应用上传到应用和扩展程序管理页面(请参阅发布)。
"permissions": [
"identity"
]
将密钥复制到您的清单中
在 Google OAuth 控制台中注册应用时,您需要提供应用的 ID,系统会在令牌请求期间检查此 ID。因此,在开发过程中使用一致的应用 ID 非常重要。
如需使应用 ID 保持不变,您需要将已安装的 manifest.json
中的密钥复制到源清单中。这不是最完美的任务,但方法如下:
- 转到您的用户数据目录。MacO 上的示例:
~/Library/Application\ Support/Google/Chrome/Default/Extensions
- 列出已安装的应用和扩展程序,并将应用和扩展程序管理页面上的应用 ID 与此处的同一 ID 进行匹配。
- 前往已安装的应用目录(这将是应用 ID 中的一个版本)。打开已安装的
manifest.json
(pico 是一种快速打开文件的方法)。 - 复制已安装的
manifest.json
中的“key”,并将其粘贴到应用的源清单文件中。
获取您的 OAuth2 客户端 ID
您需要在 Google API 控制台中注册您的应用,以获取客户端 ID:
- 使用您将应用上传到 Chrome 应用商店时所用的 Google 帐号登录 Google API 控制台。
- 展开左上角的下拉菜单,然后选择创建...菜单项,创建一个新项目。
- 创建并命名后,请转到“服务”导航菜单项,然后开启您的应用所需的所有 Google 服务。
- 前往“API 访问权限”导航菜单项,然后点击创建 OAuth 2.0 客户端 ID...蓝色按钮。
- 输入所需的品牌信息,然后选择已安装的应用类型。
- 选择 Chrome 应用,然后输入您的应用 ID(与应用和扩展程序管理页面中显示的 ID 相同)。
使用 OAuth2 客户端 ID 和范围更新清单
您需要更新清单,以包含客户端 ID 和范围。以下是 gdrive 示例的示例“oauth2”:
"oauth2": {
"client_id": "665859454684.apps.googleusercontent.com",
"scopes": [
"https://www.googleapis.com/auth/drive"
]
}
获取访问令牌
您现在可以通过调用 identity.getAuthToken 获取身份验证令牌。
chrome.identity.getAuthToken({ 'interactive': true }, function(token) {
// Use the token.
});
用户互动
调用 getAuthToken
时,您可以传递一个标志(上例中的 'interactive': true
),指示您希望在交互模式还是静默模式下调用 API。如果您在交互模式下调用该 API,系统会在必要时向用户显示登录和/或审批界面,如以下屏幕截图所示:
如果您在静默模式下调用 API,则只有在可以生成令牌而不显示任何界面的情况下,API 才会返回令牌。例如,当应用在应用启动时执行流程时,或通常不涉及用户手势时,这很有用。
我们建议的最佳实践是在不涉及用户手势时使用静默模式,如果有用户手势(例如,用户点击了应用中的登录按钮),则使用交互模式。请注意,我们并未强制要求使用任何手势。
缓存
Chrome 具有访问令牌的内存缓存,因此您可以在需要使用令牌时随时调用 getAuthToken
。令牌过期由缓存自动处理。
您可以在 chrome://identity-internals
上查看令牌缓存的当前状态。
在某些情况下,例如用户更改密码时,未过期的访问令牌将停止工作。使用此令牌的 API 调用将开始返回 HTTP 状态代码 401。如果您检测到这种情况发生了,可以通过调用 identity.removeCachedAuthToken 从 Chrome 的缓存中移除无效令牌。
removeCachedAuthToken
用法示例:
// callback = function (error, httpStatus, responseText);
function authenticatedXhr(method, url, callback) {
var retry = true;
function getTokenAndXhr() {
chrome.identity.getAuthToken({/* details */},
function (access_token) {
if (chrome.runtime.lastError) {
callback(chrome.runtime.lastError);
return;
}
var xhr = new XMLHttpRequest();
xhr.open(method, url);
xhr.setRequestHeader('Authorization',
'Bearer ' + access_token);
xhr.onload = function () {
if (this.status === 401 && retry) {
// This status may indicate that the cached
// access token was invalid. Retry once with
// a fresh token.
retry = false;
chrome.identity.removeCachedAuthToken(
{ 'token': access_token },
getTokenAndXhr);
return;
}
callback(null, this.status, this.responseText);
}
});
}
}
非 Google 账号身份验证
以下是您需要完成的三个步骤:
- 向提供商注册。
- 为您的应用将访问的提供程序资源添加权限。
- 获取身份验证令牌。
向提供商注册
您需要向提供方注册 OAuth2 客户端 ID,并将该客户端 ID 配置为网站。
对于要在注册期间输入的重定向 URI,请使用以下形式的网址:https://<extension-id>.chromiumapp.org/<anything-here>
例如,如果您的应用 ID 是 abcdefghijklmnopqrstuvwxyzabcdef
,并且您希望将 provider_cb
作为路径,以便通过重定向 URI 将其与其他提供程序区分开来,则应使用:https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb
为提供方添加权限
如需向提供程序 API 端点发送跨源 XHR,您需要将权限中的相应模式列入许可名单:
"permissions": [
...
"https://www.website-of-provider-with-user-photos.com/photos/*"
]
获取令牌
如需获取令牌,请执行以下操作:
chrome.identity.launchWebAuthFlow(
{'url': '<url-to-do-auth>', 'interactive': true},
function(redirect_url) { /* Extract token from redirect_url */ });
<url-to-do-auth>
是用于从网站向提供程序进行身份验证的网址。例如,假设您正通过提供方执行 OAuth2 流程,使用客户端 ID 123456789012345 注册了您的应用,并且您希望访问该提供方网站上的用户照片:https://www.website-of-provider-with-user-photos.com/dialog/oauth?client_id=123456789012345& redirect_uri=https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb&response_type=token&scope=user_photos
提供方将执行身份验证,并在适当的情况下向用户显示登录和/或审批界面。然后,它会重定向到 https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authToken=<auth-token>
Chrome 将捕获该字符串,并使用完整的重定向网址调用应用的回调函数。应用应从网址中提取令牌。
互动模式与静音模式
调用 launchWebAuthFlow
时,您可以传递一个标志(上例中的 'interactive': true
),指示您是否要在交互模式(也称为静默模式)下调用 API。如果您在交互模式下调用 API,如有必要,系统会向用户显示用于获取令牌的界面(登录界面和/或审批界面;或者任何特定于提供方的界面)。
如果您在静默模式下调用 API,则只有当提供程序能够在不显示任何界面的情况下提供令牌时,API 才会返回令牌。例如,当应用在应用启动时执行流程时,或者通常不涉及用户手势时,这非常有用。
我们建议的最佳实践是在不涉及用户手势时使用静默模式,如果有用户手势(例如,用户点击了应用中的登录按钮),则使用交互模式。请注意,我们并未强制要求使用手势。