chrome.identity

refresh date: 2026-09-25 robots: noindex

说明

使用 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 Web 账号。

• 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

  number 可选

  Chrome 113 及更高版本

  允许 launchWebAuthFlow 在非交互模式下运行的总时长上限（以毫秒为单位）。仅在 interactive 为 false 时有效。

• 网址

  字符串

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

方法

clearAllCachedAuthTokens()

Promise Chrome 87 及更高版本

chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
): Promise<void>

重置 Identity API 的状态：

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

参数

• callback

  函数可选

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 106 及更高版本

  返回一个 Promise，该 Promise 会在状态清除后解析。

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

getAccounts()

Promise 开发渠道

chrome.identity.getAccounts(
  callback?: function,
): Promise<AccountInfo[]>

检索 AccountInfo 对象列表，其中描述了个人资料中存在的账号。

getAccounts 仅在开发渠道中受支持。

参数

• callback

  函数可选

  callback 参数如下所示：

  (accounts: AccountInfo[]) => void

  • 账号

    AccountInfo[]

返回

• Promise<AccountInfo[]>

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

getAuthToken()

Promise

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

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

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

为了提供良好的用户体验，请务必通过应用中的界面发起交互式令牌请求，并说明授权的用途。否则，用户会收到授权请求，或者在未登录的情况下看到 Chrome 登录界面，但没有任何上下文信息。具体而言，请勿在应用首次启动时以交互方式使用 getAuthToken。

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

参数

• 详细信息

  TokenDetails 可选

  令牌选项。

• callback

  函数可选

  callback 参数如下所示：

  (result: GetAuthTokenResult) => void

  • 结果

    GetAuthTokenResult

    Chrome 105 及更高版本

返回

• Promise<GetAuthTokenResult>

  Chrome 105 及更高版本

  返回一个 Promise，该 Promise 会使用清单指定的 OAuth2 访问令牌进行解析，或者在出错时拒绝。自 Chrome 87 起，系统会填充 grantedScopes 参数。如果可用，此参数会包含与返回的令牌对应的已授予范围列表。

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

getProfileUserInfo()

Promise

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

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

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

此 API 与 identity.getAccounts 有两点不同。返回的信息可离线访问，并且仅适用于该个人资料的主账号。

参数

• 详细信息

  ProfileDetails 可选

  Chrome 84 及更高版本

  个人资料选项。

• callback

  函数可选

  callback 参数如下所示：

  (userInfo: ProfileUserInfo) => void

  • userInfo

    ProfileUserInfo

返回

• Promise<ProfileUserInfo>

  Chrome 106 及更高版本

  返回一个 Promise，该 Promise 会解析为主要 Chrome 账号的 ProfileUserInfo；如果具有给定 details 的账号不存在，则返回一个空 ProfileUserInfo。

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

getRedirectURL()

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

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

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

参数

• 路径

  字符串 可选

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

返回

• 字符串

launchWebAuthFlow()

Promise

chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
): Promise<string | undefined>

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

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

为了提供良好的用户体验，请务必通过应用中的界面启动互动式授权流程，并说明授权的目的。否则，您的用户会收到没有上下文的授权请求。尤其要注意，不要在应用首次启动时启动交互式身份验证流程。

参数

• 详细信息

  WebAuthFlowDetails

  WebAuth 流程选项。

• callback

  函数可选

  callback 参数如下所示：

  (responseUrl?: string) => void

  • responseUrl

    字符串 可选

返回

• Promise<string | undefined>

  Chrome 106 及更高版本

  返回一个 Promise，该 Promise 会解析为重定向回应用的网址。

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

removeCachedAuthToken()

Promise

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

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

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

参数

• 详细信息

  InvalidTokenDetails

  令牌信息。

• callback

  函数可选

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 106 及更高版本

  返回一个 Promise，该 Promise 会在令牌从缓存中移除后解析。

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

事件

onSignInChanged

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

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

参数

• callback

  函数

  callback 参数如下所示：

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

  • 账号

    AccountInfo

  • signedIn

    布尔值