说明
使用 chrome.identity
API 获取 OAuth2 访问令牌。
权限
identity
类型
AccountInfo
属性
-
id
string
帐号的唯一标识符。此 ID 在帐号有效期内不会更改。
AccountStatus
枚举
"SYNC"
指定为主帐号启用同步功能。
"ANY"
指明是否存在主账号(如果有)。
GetAuthTokenResult
属性
-
grantedScopes
string[] 可选
向扩展程序授予的 OAuth2 范围的列表。
-
token
字符串(可选)
与请求关联的特定令牌。
InvalidTokenDetails
属性
-
token
string
应从缓存中移除的特定令牌。
ProfileDetails
属性
-
accountStatus
AccountStatus(可选)
登录到个人资料(应返回
ProfileUserInfo
)的主账号的状态。默认设置为SYNC
帐号状态。
ProfileUserInfo
属性
-
电子邮件地址
string
登录到当前个人资料的用户账号的电子邮件地址。如果用户未登录,或未指定
identity.email
清单权限,则为空。 -
id
string
帐号的唯一标识符。此 ID 在帐号有效期内不会更改。如果用户未登录,或(在 M41 及更高版本)未指定
identity.email
清单权限,则为空。
TokenDetails
属性
-
账号
AccountInfo(选填)
应返回其令牌的帐号 ID。如果未指定,函数将使用 Chrome 个人资料中的帐号:同步帐号(如果有),否则使用第一个 Google 网络帐号。
-
enableGranularPermissions
布尔值 选填
Chrome 87 及更高版本enableGranularPermissions
标志允许扩展程序尽早选择启用精细权限同意屏幕,在该屏幕中单独授予或拒绝请求的权限。 -
interactive
布尔值 选填
获取令牌可能需要用户登录 Chrome,或批准应用请求的范围。如果互动标志为
true
,getAuthToken
将根据需要提示用户。如果标志为false
或省略,则每次需要提示时,getAuthToken
都会返回失败。 -
scopes
string[] 可选
要请求的 OAuth2 范围列表。
如果
scopes
字段存在,它将替换 manifest.json 中指定的范围列表。
WebAuthFlowDetails
属性
-
abortOnLoadForNonInteractive
布尔值 选填
Chrome 113 及更高版本是否在网页加载后终止非交互式请求的
launchWebAuthFlow
。此参数不会影响交互式流程。如果设置为
true
(默认),该数据流将在页面加载后立即终止。如果设置为false
,则 flow 仅在timeoutMsForNonInteractive
过后终止。这对于在网页加载后使用 JavaScript 执行重定向的身份提供方非常有用。 -
interactive
布尔值 选填
是否以交互模式启动身份验证流程。
由于某些身份验证流程可能会立即重定向到结果网址,因此
launchWebAuthFlow
会隐藏其网页视图,直到第一次导航重定向到最终到达网址或完成要显示的网页的加载为止。如果
interactive
标志为true
,则系统会在页面加载完成后显示窗口。如果该标志为false
或省略该标志,则当初始导航未完成该流程时,launchWebAuthFlow
将返回错误。对于使用 JavaScript 进行重定向的流,可以将
abortOnLoadForNonInteractive
设置为false
,同时设置timeoutMsForNonInteractive
以使网页有机会执行任何重定向。 -
timeoutMsForNonInteractive
数字可选
Chrome 113 及更高版本在非互动模式下运行
launchWebAuthFlow
的总时长上限(以毫秒为单位)。仅当interactive
为false
时才有效。 -
网址
string
启动身份验证流程的网址。
方法
clearAllCachedAuthTokens()
chrome.identity.clearAllCachedAuthTokens(
callback?: function,
)
重置 Identity API 的状态:
- 从令牌缓存中移除所有 OAuth2 访问令牌
- 移除用户的账号偏好设置
- 取消所有身份验证流程的用户授权
参数
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 106 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getAccounts()
chrome.identity.getAccounts(
callback?: function,
)
用于检索描述个人资料上显示的帐号的 AccountInfo 对象列表。
只有开发者版支持getAccounts
。
参数
-
callback
函数(可选)
callback
参数如下所示:(accounts: AccountInfo[]) => void
-
账户
-
返回
-
Promise<AccountInfo[]>
只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getAuthToken()
chrome.identity.getAuthToken(
details?: TokenDetails,
callback?: function,
)
使用 manifest.json 的 oauth2
部分中指定的客户端 ID 和范围获取 OAuth2 访问令牌。
Identity API 会将访问令牌缓存在内存中,因此每当需要令牌时,都可以以非交互方式调用 getAuthToken
。令牌缓存会自动处理到期时间。
为了提供良好的用户体验,请务必注意,交互式令牌请求应由应用中的界面发起,以说明授权的用途。否则,您的用户会收到授权请求或 Chrome 登录屏幕(如果他们未登录),且无法提供背景信息。特别是,在应用首次启动时,请勿以交互方式使用 getAuthToken
。
注意: 使用回调进行调用时,此函数不会返回对象,而是将返回这两个属性作为分别传递到该回调的参数。
参数
-
详细信息
TokenDetails(可选)
令牌选项。
-
callback
函数(可选)
callback
参数如下所示:(result: GetAuthTokenResult) => void
-
Chrome 105 及更高版本
-
返回
-
Promise<GetAuthTokenResult>
Chrome 105 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getProfileUserInfo()
chrome.identity.getProfileUserInfo(
details?: ProfileDetails,
callback?: function,
)
检索已登录个人资料的用户的电子邮件地址和经过混淆处理的 GAIA ID。
需要 identity.email
清单权限。否则,返回空结果。
此 API 与 identity.getAccounts 的不同之处体现在两个方面。返回的信息可在离线状态下查看,而且仅适用于个人资料的主账号。
参数
-
详细信息Chrome 84 及更高版本
个人资料选项。
-
callback
函数(可选)
callback
参数如下所示:(userInfo: ProfileUserInfo) => void
-
userInfo
-
返回
-
Promise<ProfileUserInfo>
Chrome 106 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getRedirectURL()
chrome.identity.getRedirectURL(
path?: string,
)
生成要在 launchWebAuthFlow
中使用的重定向网址。
生成的网址与 https://<app-id>.chromiumapp.org/*
格式匹配。
参数
-
path
字符串(可选)
附加到所生成网址末尾的路径。
返回
-
string
launchWebAuthFlow()
chrome.identity.launchWebAuthFlow(
details: WebAuthFlowDetails,
callback?: function,
)
在指定的网址启动身份验证流程。
此方法通过启动网页视图并将其转到提供方身份验证流程中的第一个网址,来启用使用非 Google 身份提供方身份验证流程。当提供程序重定向到与格式 https://<app-id>.chromiumapp.org/*
匹配的网址时,该窗口将关闭,并将最终重定向网址传递给 callback
函数。
为了提供良好的用户体验,重要的交互式身份验证流程应由应用中的界面启动,以说明授权的用途。否则,您的用户将收到没有背景信息的授权请求。具体来说,首次启动您的应用时,不要启动交互式身份验证流程。
参数
-
详细信息
WebAuth 流程选项。
-
callback
函数(可选)
callback
参数如下所示:(responseUrl?: string) => void
-
responseUrl
字符串(可选)
-
返回
-
Promise<string | undefined>
Chrome 106 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
removeCachedAuthToken()
chrome.identity.removeCachedAuthToken(
details: InvalidTokenDetails,
callback?: function,
)
从 Identity API 的令牌缓存中移除 OAuth2 访问令牌。
如果发现访问令牌无效,应将其传递至 removeCachedAuthToken,以将其从缓存中移除。然后,应用可能会使用 getAuthToken
检索新的令牌。
参数
-
详细信息
令牌信息。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 106 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
活动
onSignInChanged
chrome.identity.onSignInChanged.addListener(
callback: function,
)
在用户个人资料的账号登录状态发生变化时触发。
参数
-
callback
功能
callback
参数如下所示:(account: AccountInfo, signedIn: boolean) => void
-
账号
-
signedIn
boolean
-