chrome.identity

说明

使用 chrome.identity API 获取 OAuth2 访问令牌。

权限

identity

类型

AccountInfo

属性

  • id

    字符串

    账号的唯一标识符。在账号的整个有效期内，此 ID 不会发生变化。

AccountStatus

Chrome 84 及更高版本

枚举

"SYNC"
指定为主账号启用同步功能。

"ANY"
指定是否存在主账号（如果有）。

GetAuthTokenResult

Chrome 105 及更高版本

属性

  • grantedScopes

    string[] 选填

    向扩展程序授予的 OAuth2 范围列表。

  • token

    字符串（可选）

    与请求关联的特定令牌。

InvalidTokenDetails

属性

  • token

    字符串

    应从缓存中移除的特定令牌。

ProfileDetails

Chrome 84 及更高版本

属性

  • accountStatus

    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()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 87 及更高版本 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
)

重置 Identity API 的状态：

  • 从令牌缓存中移除所有 OAuth2 访问令牌
  • 移除用户的账号偏好设置
  • 从所有身份验证流程中取消对用户的授权

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 106 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getAccounts()

<ph type="x-smartling-placeholder"></ph> 承诺 开发者版 
chrome.identity.getAccounts(
  callback?: function,
)

检索 AccountInfo 对象列表，用于描述个人资料上存在的账号。

仅开发版支持 getAccounts。

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (accounts: AccountInfo[]) => void

返回

  • Promise&lt;AccountInfo[]&gt;

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getAuthToken()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
)

使用 manifest.json 的 oauth2 部分中指定的客户端 ID 和范围获取 OAuth2 访问令牌。

Identity API 将访问令牌缓存在内存中，因此可以在需要令牌时以非交互方式调用 getAuthToken。令牌缓存会自动处理过期问题。

为了提供良好的用户体验，重要的交互式令牌请求应由应用中的界面发起，解释授权的用途。否则，您的用户会收到授权请求或 Chrome 登录屏幕（如果他们未登录，并且没有上下文）。特别是，当您的应用首次启动时，不要以交互方式使用 getAuthToken。

注意： 使用回调进行调用时，此函数将返回两个属性作为传递给回调的单独参数，而不是返回对象。

参数

返回

  • Promise&lt;GetAuthTokenResult&gt;

    Chrome 105 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getProfileUserInfo()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
)

检索已登录配置文件的用户的电子邮件地址和经过混淆处理的 GAIA ID。

需要 identity.email 清单权限。否则，返回空结果。

此 API 与 identity.getAccounts 有以下两点。返回的信息可在离线状态下查看，并且仅适用于相应商家资料的主账号。

参数

返回

  • Promise&lt;ProfileUserInfo&gt;

    Chrome 106 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getRedirectURL()

chrome.identity.getRedirectURL(
  path?: string,
)

生成要在 launchWebAuthFlow 中使用的重定向网址。

生成的网址与格式 https://<app-id>.chromiumapp.org/* 匹配。

参数

  • 路径

    字符串（可选）

    附加到所生成网址末尾的路径。

返回

  • 字符串

launchWebAuthFlow()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
)

在指定的网址启动身份验证流程。

此方法通过启动网页视图并将其导航到提供商身份验证流程中的第一个网址，启用针对非 Google 身份提供方的身份验证流程。当提供程序重定向到与 https://<app-id>.chromiumapp.org/* 格式匹配的网址时，该窗口将关闭，最终重定向网址将会传递给 callback 函数。

为了提供良好的用户体验，重要的交互式身份验证流程应由应用中的界面启动，解释授权的用途。否则，您的用户将收到没有上下文的授权请求。尤其要注意，不要在首次启动您的应用时启动交互式身份验证流程。

参数

  • 详细信息

    WebAuthFlowDetails

    WebAuth 流选项。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (responseUrl?: string) => void

    • responseUrl

      字符串（可选）

返回

  • Promise<string |未定义>

    Chrome 106 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

removeCachedAuthToken()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
)

从 Identity API 的令牌缓存中移除 OAuth2 访问令牌。

如果发现访问令牌无效，则应将该令牌传递给 removeCachedAuthToken，以将其从缓存中移除。然后，应用可以使用 getAuthToken 检索新的令牌。

参数

  • 详细信息

    InvalidTokenDetails

    令牌信息。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 106 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

onSignInChanged

chrome.identity.onSignInChanged.addListener(
  callback: function,
)

用户个人资料中账号的登录状态发生变化时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (account: AccountInfo, signedIn: boolean) => void