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