本参考文档介绍了 Google 第三方授权 JavaScript 库 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 ,系统将提供更精细的 Google 账号权限
将对 2019 年之前创建的 OAuth 客户端 ID 停用。如果同时设置了 enable_granular_consent 和 enable_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 |
可选。用于授权流程的用户体验模式。默认情况下,它会在弹出式窗口中打开意见征求流程。有效值为 popup 和 redirect 。
|
select_account |
可选,默认为 'false'。用于提示用户选择账号的布尔值。 |
error_callback |
可选。JavaScript 函数用于处理某些非 OAuth 错误,例如
弹出式窗口无法打开;或关闭之前
返回。
输入参数的“type”字段会提供详细原因。
|
数据类型:CodeClient
该类只有一个公共方法 requestCode,该方法会启动 OAuth 2.0 代码用户体验流程。
interface CodeClient {
requestCode(): void;
}
数据类型:CodeResponse
系统会将 CodeResponse
JavaScript 对象传递给 callback
方法
弹出用户体验在重定向用户体验中,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'。以空格分隔
向用户显示的提示列表(区分大小写)。可能的值包括:
<ph type="x-smartling-placeholder">
|
enable_granular_consent |
可选,默认为 true 。如果设为 false ,系统将提供更精细的 Google 账号权限
将对 2019 年之前创建的 OAuth 客户端 ID 停用。如果同时设置了 enable_granular_consent 和 enable_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 |
可选。JavaScript 函数用于处理某些非 OAuth 错误,例如
弹出式窗口无法打开;或关闭之前
返回。
输入参数的“type”字段会提供详细原因。
|
数据类型: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 ,系统将提供更精细的 Google 账号权限
对于 2019 年之前创建的 OAuth 客户端 ID,系统会停用此设置。如果同时设置了 enable_granular_consent 和 enable_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 |
字符串 | 必需。要检查的范围。 |
restScopes |
字符串[] | 可选。要检查的其他范围。 |
返回 | |
---|---|
布尔值 | 如果授予所有范围,则为 true。 |
方法:google.accounts.oauth2.hasGrantedAnyScope
检查用户是否授予了一个或多个指定范围。
google.accounts.oauth2.hasGrantedAnyScope(
tokenResponse: TokenResponse,
firstScope: string, ...restScopes: string[]
): boolean;
参数 | ||
---|---|---|
tokenResponse |
TokenResponse
|
必需。TokenResponse
对象。
|
firstScope |
字符串 | 必需。要检查的范围。 |
restScopes |
字符串[] | 可选。要检查的其他范围。 |
返回 | |
---|---|
布尔值 | 如果授予了任何范围,则为 true。 |
方法:google.accounts.oauth2.revoke
revoke
方法可撤消用户向应用授予的所有范围。
必须提供有效的访问令牌才能撤消权限。
google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
参数 | ||
---|---|---|
accessToken |
字符串 | 必需。有效的访问令牌。 |
callback |
函数 | 可选。RevocationResponse 处理程序。 |
数据类型:RevocationResponse
系统会将 RevocationResponse
JavaScript 对象传递给回调方法。
下表列出了 RevocationResponse
数据类型的属性。
属性 | |
---|---|
successful |
布尔值。true 表示成功,false 表示失败。 |
error |
字符串。成功时未定义。单个 ASCII 错误代码。这包括但不限于标准 OAuth
2.0 错误代码。revoke 方法的常见错误:
<ph type="x-smartling-placeholder">
|
error_description |
字符串。成功时未定义。人类可读的 ASCII 文本提供关于
error 属性。开发者可以利用这些信息
所发生的错误error_description 字符串仅提供英文版。
对于 error 中列出的常见错误,相应的 error_description :
<ph type="x-smartling-placeholder">
|