适用于网站的 Google 第三方授权 JavaScript 库 - API 参考文档

本参考文档介绍了 Google 第三方授权 JavaScript 库 API,您可以使用该 API 从 Google 加载授权代码或访问令牌。

方法:google.accounts.oauth2.initCodeClient

initCodeClient 方法会初始化并返回代码客户端,其中包含参数中的配置。

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

数据类型:CodeClientConfig

下表列出了 CodeClientConfig 数据类型的属性。

属性
client_id 必需。您的应用的客户端 ID。您可以在 API 控制台中找到此值。
scope 必需。以空格分隔的范围列表,用于标识您的应用可以代表用户访问的资源。这些值会告知 Google 向用户显示同意屏幕。
include_granted_scopes 可选,默认为 true。允许应用使用增量授权来请求在上下文中访问其他范围。如果您将此参数的值设为 false 并授予授权请求,则新的访问令牌将仅涵盖 scope 在此 CodeClientConfig 中请求的任何范围。
redirect_uri 对于重定向用户体验是必需的。确定在用户完成授权流程后 API 服务器将用户重定向到的目标位置。该值必须与您在 API 控制台中配置的 OAuth 2.0 客户端的某个已授权重定向 URI 完全匹配,并且必须符合我们的重定向 URI 验证规则。弹出式窗口用户体验将忽略该属性。
callback 对于弹出式窗口用户体验是必需的。用于处理返回的代码响应的 JavaScript 函数。 重定向用户体验将忽略该属性。
state 可选。建议用于重定向用户体验。指定您的应用用来维护授权请求和授权服务器响应之间的状态的任何字符串值。
enable_granular_consent 可选,默认为 true。如果设置为 false,则系统会为 2019 年之前创建的 OAuth 客户端 ID 停用更精细的 Google 帐号权限。如果同时设置了 enable_granular_consentenable_serial_consent,则只有 enable_granular_consent 值会生效,enable_serial_consent 值会被忽略。

对较新的 OAuth 客户端 ID 没有影响,因为系统始终会为它们启用更精细的权限。
enable_serial_consent 已弃用,应改用 enable_granular_consent。这与 enable_granular_consent 具有相同的效果。使用 enable_serial_consent 的现有应用可以继续这样使用,但建议您更新代码以便在下一次应用更新中使用 enable_granular_consent
login_hint 可选。如果您的应用知道哪个用户应向请求授权,则可以使用此属性向 Google 提供登录提示。验证成功后,系统会跳过账号选择。目标用户的电子邮件地址或 ID 令牌 sub 字段值。如需了解详情,请参阅 OpenID Connect 文档中的 login_hint 字段。
hd 可选。如果您的应用知道用户所属的 Workspace 网域,请使用此信息向 Google 提供提示。验证成功后,系统会限制为所提供的网域或为所提供的网域预先选择用户帐号。 如需了解详情,请参阅 OpenID Connect 文档中的 hd 字段。
ux_mode 可选。用于授权流程的用户体验模式。默认情况下,系统会在弹出式窗口中打开意见征求流程。有效值为 popupredirect
select_account 可选,默认为 'false'。用于提示用户选择帐号的布尔值。
error_callback 可选。用于处理某些非 OAuth 错误的 JavaScript 函数,例如弹出式窗口无法打开;或者在返回 OAuth 响应之前关闭。

输入参数的“type”字段提供了详细原因。
  • popup_failed_to_open:无法打开弹出式窗口。
  • popup_closed:在返回 OAuth 响应之前关闭弹出式窗口。
  • unknown 其他错误所对应的占位符。

数据类型:CodeClient

该类只有一个公共方法 requestCode,用于启动 OAuth 2.0 代码用户体验流程。

interface CodeClient {
  requestCode(): void;
}

数据类型:CodeResponse

系统会在弹出式窗口用户体验中向 callback 方法传递一个 CodeResponse JavaScript 对象。在重定向用户体验中,CodeResponse 将作为网址参数传递。

下表列出了 CodeResponse 数据类型的属性。

属性
code 成功令牌响应的授权代码。
scope 用户批准的范围列表(用空格分隔)。
state 您的应用用来维护授权请求和响应之间的状态的字符串值。
error 单个 ASCII 错误代码。
error_description 提供额外信息的直观易懂的 ASCII 文本,用于帮助客户端开发者了解发生的错误。
error_uri 用于标识包含错误相关信息的人类可读网页的 URI,用于为客户端开发者提供有关错误的其他信息。

方法:google.accounts.oauth2.initTokenClient

initTokenClient 方法会初始化并返回令牌客户端,其中包含参数中的配置。

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

数据类型:TokenClientConfig

下表列出了 TokenClientConfig 数据类型的属性。

属性
client_id 必需。您的应用的客户端 ID。您可以在 API 控制台中找到这个值。
callback 必需。用于处理返回的令牌响应的 JavaScript 函数。
scope 必需。以空格分隔的范围列表,用于标识您的应用可以代表用户访问的资源。这些值会告知 Google 向用户显示同意屏幕。
include_granted_scopes 可选,默认为 true。允许应用使用增量授权来请求在上下文中访问其他范围。如果您将此参数的值设为 false 并授予授权请求,则新的访问令牌将仅涵盖 scope 在此 TokenClientConfig 中请求的任何范围。
prompt 可选,默认为 'select_account'。向用户显示的提示列表(以空格分隔,区分大小写)。可能的值包括:
  • 空字符串:只有当您的应用首次请求访问权限时,系统才会提示用户。无法使用其他值指定。
  • 'none' 不显示任何身份验证或同意屏幕。不得使用其他值指定。
  • 'consent' 提示用户同意。
  • 'select_account' 提示用户选择帐号。
enable_granular_consent 可选,默认为 true。如果设置为 false,则系统会为 2019 年之前创建的 OAuth 客户端 ID 停用更精细的 Google 帐号权限。如果同时设置了 enable_granular_consentenable_serial_consent,则只有 enable_granular_consent 值会生效,enable_serial_consent 值会被忽略。

对较新的 OAuth 客户端 ID 没有影响,因为系统始终会为它们启用更精细的权限。
enable_serial_consent 已弃用,应改用 enable_granular_consent。这与 enable_granular_consent 具有相同的效果。使用 enable_serial_consent 的现有应用可以继续这样使用,但建议您更新代码以便在下一次应用更新中使用 enable_granular_consent
login_hint 可选。如果您的应用知道哪个用户应向请求授权,则可以使用此属性向 Google 提供登录提示。验证成功后,系统会跳过账号选择。目标用户的电子邮件地址或 ID 令牌 sub 字段值。如需了解详情,请参阅 OpenID Connect 文档中的 login_hint 字段。
hd 可选。如果您的应用知道用户所属的 Workspace 网域,请使用此信息向 Google 提供提示。验证成功后,系统会限制为所提供的网域或为所提供的网域预先选择用户帐号。 如需了解详情,请参阅 OpenID Connect 文档中的 hd 字段。
state 可选。不推荐。指定您的应用用来维护授权请求和授权服务器响应之间的状态的任何字符串值。
error_callback 可选。用于处理某些非 OAuth 错误的 JavaScript 函数,例如弹出式窗口无法打开;或者在返回 OAuth 响应之前关闭。

输入参数的“type”字段提供了详细原因。
  • popup_failed_to_open:无法打开弹出式窗口。
  • popup_closed:在返回 OAuth 响应之前关闭弹出式窗口。
  • unknown 其他错误所对应的占位符。

数据类型:TokenClient

该类只有一个公共方法 requestAccessToken,用于启动 OAuth 2.0 令牌用户体验流程。

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
参数
overrideConfig OverridableTokenClientConfig 可选。要在此方法中替换的配置。

数据类型:OverridableTokenClientConfig

下表列出了 OverridableTokenClientConfig 数据类型的属性。

属性
scope 可选。以空格分隔的范围列表,用于标识您的应用可以代表用户访问的资源。这些值会告知 Google 向用户显示的权限请求页面。
include_granted_scopes 可选,默认为 true。允许应用使用增量授权来请求在上下文中访问其他范围。如果您将此参数的值设为 false 并授予授权请求,则新的访问令牌将仅涵盖 scope 在此 OverridableTokenClientConfig 中请求的任何范围。
prompt 可选。向用户显示的提示列表(以空格分隔,区分大小写)。
enable_granular_consent 可选,默认为 true。如果设为 false,对于 2019 年之前创建的 OAuth 客户端 ID,系统将停用更精细的 Google 帐号权限。如果同时设置了 enable_granular_consentenable_serial_consent,则只有 enable_granular_consent 值会生效,并且 enable_serial_consent 值会被忽略。

对较新的 OAuth 客户端 ID 没有影响,因为系统始终会为它们启用更精细的权限。
enable_serial_consent 已弃用,应改用 enable_granular_consent。这与 enable_granular_consent 具有相同的效果。使用 enable_serial_consent 的现有应用可以继续这样使用,但建议您更新代码以便在下一次应用更新中使用 enable_granular_consent
login_hint 可选。如果您的应用知道哪个用户应向请求授权,则可以使用此属性向 Google 提供登录提示。验证成功后,系统会跳过账号选择。目标用户的电子邮件地址或 ID 令牌 sub 字段值。如需了解详情,请参阅 OpenID Connect 文档中的 login_hint 字段。
state 可选。不推荐。指定您的应用用来维护授权请求和授权服务器响应之间的状态的任何字符串值。

数据类型:TokenResponse

系统会在弹出式窗口用户体验中向回调方法传递一个 TokenResponse JavaScript 对象。

下表列出了 TokenResponse 数据类型的属性。

属性
access_token 成功令牌响应的访问令牌。
expires_in 访问令牌的生命周期(以秒为单位)。
hd 已登录用户所属的托管网域。
prompt 使用的提示值,可能来自 TokenClientConfig 或 OverridableTokenClientConfig 指定的可能值列表。
token_type 颁发的令牌的类型。
scope 用户批准的范围列表(用空格分隔)。
state 您的应用用来维护授权请求和响应之间的状态的字符串值。
error 单个 ASCII 错误代码。
error_description 提供额外信息的直观易懂的 ASCII 文本,用于帮助客户端开发者了解发生的错误。
error_uri 用于标识包含错误相关信息的人类可读网页的 URI,用于为客户端开发者提供有关错误的其他信息。

方法:google.accounts.oauth2.hasGrantedAllScopes

检查用户是否授予了所有指定的范围。

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;
参数
tokenResponse TokenResponse 必需TokenResponse 对象。
firstScope string 必需。要检查的范围。
restScopes 字符串[] 可选。要检查的其他范围。
返回
boolean 如果授予了所有范围,则为 true。

方法:google.accounts.oauth2.hasGrantedAnyScope

检查用户是否授予了任何指定的范围。

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
参数
tokenResponse TokenResponse 必需TokenResponse 对象。
firstScope string 必需。要检查的范围。
restScopes 字符串[] 可选。要检查的其他范围。
返回
boolean 如果授予了任何范围,则为 true。

方法:google.accounts.oauth2.revoke

revoke 方法可撤消用户向应用授予的所有范围。撤消权限需要使用有效的访问令牌。

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
参数
accessToken 字符串 必需。有效的访问令牌。
callback function 可选。RevocationResponse 处理程序中。

数据类型:RevocationResponse

系统会向您的回调方法传递一个 RevocationResponse JavaScript 对象。

下表列出了 RevocationResponse 数据类型的属性。

属性
successful 布尔值。true 成功,false 表示失败。
error 字符串。成功时未定义。单个 ASCII 错误代码。这包括但不限于标准 OAuth 2.0 错误代码revoke 方法的常见错误:
  • invalid_token - 在调用 revoke 方法之前令牌已过期或被撤消。在大多数情况下,您可以认为与 accessToken 关联的授权已被撤消。
  • invalid_request - 令牌不可撤消。您应确保 accessToken 是有效的 Google OAuth 2.0 凭据。
error_description 字符串。成功时未定义。人类可读的 ASCII 文本提供有关 error 属性的更多信息。开发者可以利用此信息更好地了解发生的错误。error_description 字符串仅提供英文版。对于 error 中列出的常见错误,对应 error_description
  • invalid_token - 令牌已过期或被撤消。
  • invalid_request - 令牌不可撤消。