Scripting
文档
更新日志
隐私
文档
更新日志
隐私
简体中文

OAuth2

OAuth2 类用于在脚本中实现 OAuth 2.0 授权流程。它支持标准的授权码流程、PKCE（Proof Key for Code Exchange）、访问令牌续期及多种配置选项。

构造函数

1new OAuth2(options: {
2  consumerKey: string
3  consumerSecret: string
4  authorizeUrl: string
5  accessTokenUrl?: string
6  responseType: string
7  contentType?: string
8})

参数说明

参数名 类型 是否必填 说明
consumerKey string 是 应用的客户端 ID（Client ID）或 Consumer Key。
consumerSecret string 是 应用的客户端密钥（Client Secret）。
authorizeUrl string 是 用于跳转用户授权的地址。
accessTokenUrl string 否 获取访问令牌（Access Token）的地址，若不提供则使用 authorizeUrl。
responseType string 是 一般为 "code"，表示使用授权码流程。
contentType string 否 请求令牌时使用的内容类型，默认值为 "application/x-www-form-urlencoded"。

抛出错误

  • 当配置参数无效或实例化失败时抛出错误。

属性

accessTokenBasicAuthentification: boolean

是否使用 Basic 认证方式发送获取访问令牌的请求。默认值为 false。

allowMissingStateCheck: boolean

是否禁用 state 参数校验（CSRF 保护）。谨慎使用，默认值为 false。

encodeCallbackURL: boolean

是否对回调地址进行 URL 编码。某些服务商要求必须编码。默认值为 true。

encodeCallbackURLQuery: boolean

是否对整个回调地址的查询参数进行编码。部分服务如 Imgur 要求此值为 false。默认值为 true。

方法

authorize(options): Promise<OAuthCredential>

发起 OAuth2 授权流程。将打开一个浏览器窗口，供用户登录并授权。

1authorize(options: {
2  callbackURL?: string
3  scope: string
4  state: string
5  parameters?: Record<string, any>
6  headers?: Record<string, string>
7} & ({
8  codeVerifier: string
9  codeChallenge: string
10  codeChallengeMethod: string
11} | {
12  codeVerifier?: never
13  codeChallenge?: never
14  codeChallengeMethod?: never
15})): Promise<OAuthCredential>

参数说明

参数名 类型 是否必填 说明
callbackURL string 否 授权成功后的回调地址，默认为 scripting://oauth_callback/脚本名称。
scope string 是 空格分隔的权限列表。
state string 是 防止 CSRF 攻击的随机字符串。
parameters Record<string, any> 否 附加的授权请求参数。
headers Record<string, string> 否 附加的请求头。
codeVerifier string 条件必填 PKCE 流程中使用的随机码。
codeChallenge string 条件必填 由 codeVerifier 生成的哈希值。
codeChallengeMethod "plain" | "S256" 条件必填 PKCE 中的 challenge 加密方法，默认使用 "S256"。

返回值

  • 返回一个包含授权结果的 OAuthCredential 对象。

抛出错误

  • 若用户拒绝授权或网络错误将抛出异常。

示例

1const oauth = new OAuth2({
2  consumerKey: '你的客户端ID',
3  consumerSecret: '你的客户端密钥',
4  authorizeUrl: 'https://provider.com/oauth/authorize',
5  accessTokenUrl: 'https://provider.com/oauth/token',
6  responseType: 'code'
7})
8
9const credential = await oauth.authorize({
10  scope: 'profile email',
11  state: 'secure_random_state',
12  callbackURL: Script.createOAuthCallbackURLScheme('my_oauth_script')
13})
14
15console.log(credential.oauthToken)

renewAccessToken(options): Promise<OAuthCredential>

使用刷新令牌（refresh token）重新获取访问令牌。

1renewAccessToken(options: {
2  refreshToken: string
3  parameters?: Record<string, any>
4  headers?: Record<string, string>
5}): Promise<OAuthCredential>

参数说明

参数名 类型 是否必填 说明
refreshToken string 是 上一次授权返回的刷新令牌。
parameters Record<string, any> 否 额外的 POST 请求参数。
headers Record<string, string> 否 自定义请求头。

返回值

  • 返回新的 OAuthCredential 对象。

抛出错误

  • 若刷新失败（如刷新令牌已过期），则抛出错误。

示例

1const newCredential = await oauth.renewAccessToken({
2  refreshToken: oldCredential.oauthRefreshToken
3})
4
5console.log(newCredential.oauthToken)

OAuthCredential 类型定义

授权成功后返回的凭证对象包含以下字段：

1type OAuthCredential = {
2  oauthToken: string
3  oauthTokenSecret: string
4  oauthRefreshToken: string
5  oauthTokenExpiresAt: number | null
6  oauthVerifier: string
7  version: string
8  signatureMethod: string
9}

字段说明

字段名 类型 说明
oauthToken string 用于访问资源的 Access Token。
oauthTokenSecret string 与访问令牌配套使用的 Token Secret，常用于 OAuth1.0 流程。
oauthRefreshToken string 用于获取新访问令牌的 Refresh Token。
oauthTokenExpiresAt number | null 访问令牌的过期时间（Unix 毫秒时间戳），若无过期则为 null。
oauthVerifier string 在 PKCE 流程中使用的授权码验证器。
version string OAuth 协议版本（例如 "2.0"）。
signatureMethod string 请求签名方式（如 "HMAC-SHA1"、"PLAINTEXT"）。

使用建议

  • 始终使用 state 参数防止 CSRF 攻击，除非明确关闭。
  • 使用 Script.createOAuthCallbackURLScheme(name) 为脚本生成唯一回调地址。
  • 若需要长期授权，请妥善保存 oauthRefreshToken。
  • 对于公用客户端建议启用 PKCE 增强安全性。
大纲