chrome.identity

说明

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

权限

identity

类型

AccountInfo

属性

  • id

    string

    帐号的唯一标识符。此 ID 在帐号有效期内不会更改。

AccountStatus

Chrome 84 及更高版本

枚举

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

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

GetAuthTokenResult

Chrome 105 及更高版本

属性

  • grantedScopes

    string[] 可选

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

  • token

    字符串（可选）

    与请求关联的特定令牌。

InvalidTokenDetails

属性

  • token

    string

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

ProfileDetails

Chrome 84 及更高版本

属性

  • accountStatus

    AccountStatus（可选）

    登录到个人资料（应返回 ProfileUserInfo）的主账号的状态。默认设置为 SYNC 帐号状态。

ProfileUserInfo

属性

  • email

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

Promise Chrome 87 及更高版本 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
)

重置 Identity API 的状态：

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

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 106 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getAccounts()

Promise 开发者版 
chrome.identity.getAccounts(
  callback?: function,
)

用于检索描述个人资料上显示的帐号的 AccountInfo 对象列表。

只有开发者版支持getAccounts。

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    (accounts: AccountInfo[])=>void

返回

  • Promise<AccountInfo[]>

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getAuthToken()

Promise 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
)

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

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

为了提供良好的用户体验，请务必注意，交互式令牌请求应由应用中的界面发起，以说明授权的用途。否则，您的用户会收到授权请求或 Chrome 登录屏幕（如果他们未登录），且无法提供背景信息。特别是，在应用首次启动时，请勿以交互方式使用 getAuthToken。

注意： 使用回调进行调用时，此函数不会返回对象，而是将返回这两个属性作为分别传递到该回调的参数。

参数

返回

  • Chrome 105 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getProfileUserInfo()

Promise 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
)

检索已登录个人资料的用户的电子邮件地址和经过混淆处理的 GAIA ID。

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

此 API 与 identity.getAccounts 的不同之处体现在两个方面。返回的信息可在离线状态下查看，而且仅适用于个人资料的主账号。

参数

返回

  • Promise<ProfileUserInfo>

    Chrome 106 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getRedirectURL()

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

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

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

参数

  • path

    字符串（可选）

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

返回

  • string

launchWebAuthFlow()

Promise 
chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
)

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

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

为了提供良好的用户体验，重要的交互式身份验证流程应由应用中的界面启动，以说明授权的用途。否则，您的用户将收到没有背景信息的授权请求。具体来说，首次启动您的应用时，不要启动交互式身份验证流程。

参数

  • WebAuth 流程选项。

  • callback

    函数（可选）

    callback 参数如下所示：

    (responseUrl?: string)=>void

    • responseUrl

      字符串（可选）

返回

  • Promise<字符串|未定义>

    Chrome 106 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeCachedAuthToken()

Promise 
chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
)

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

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

参数

  • 令牌信息。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 106 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

活动

onSignInChanged

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

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

参数

  • callback

    功能

    callback 参数如下所示：

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