OAuth 2.0 机制

本文档定义了 SASL XOAUTH2 机制，以用于 IMAP AUTHENTICATE、POP AUTH 和 SMTP AUTH 命令。借助此机制，您可以使用 OAuth 2.0 访问令牌向用户的 Gmail 账号进行身份验证。

使用 OAuth 2.0

首先，请熟悉使用 OAuth 2.0 访问 Google API。该文档介绍了 OAuth 2.0 的工作原理，以及编写客户端所需的步骤。

您可能还想浏览 XOAUTH2 示例代码，以了解实际示例。

OAuth 2.0 范围

IMAP、POP 和 SMTP 访问的范围是 https://mail.google.com/。如果您 请求访问 IMAP、POP 或 SMTP 应用的完整邮件范围， 则必须遵守我们的 Google API 服务：用户数据政策。

  • 如需获得批准，您的应用必须充分利用 https://mail.google.com/。
  • 如果您的应用不需要 https://mail.google.com/，请迁移到 Gmail API 并使用更精细的受限范围。

Google Workspace 的全网域授权

如果您打算使用 Google Workspace 全网域授权 通过 服务账号 使用 IMAP 访问 Google Workspace 用户的邮箱， 则可以使用范围 https://www.googleapis.com/auth/gmail.imap_admin 授权您的客户端。

使用此范围获得授权后，IMAP 连接的行为会有所不同：

  • 所有标签都会通过 IMAP 显示，即使用户在 Gmail 设置中停用了“在 IMAP 中显示”标签也是如此。
  • 所有邮件都会通过 IMAP 显示，无论用户在 Gmail 设置的“文件夹大小限制”中设置了什么。

SASL XOAUTH2 机制

借助 XOAUTH2 机制，客户端可以向服务器发送 OAuth 2.0 访问令牌。该协议使用以下部分中显示的编码值。

初始客户端响应

SASL XOAUTH2 初始客户端响应的格式如下：

base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")

使用 RFC 4648 中定义的 base64 编码机制。^A 表示 Ctrl+A (\001)。

例如，在进行 base64 编码之前，初始客户端响应可能如下所示：

user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A

进行 base64 编码后，它会变成（为清楚起见，插入了换行符）：

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

错误响应

如果初始客户端响应导致错误，服务器会发送一个质询，其中包含以下格式的错误消息：

base64({JSON-Body})

JSON-Body 包含三个值：status、schemes 和 scope。例如：

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

进行 base64 解码后，它会变成（为清楚起见，进行了格式化）：

{
  "status":"401",
  "schemes":"bearer",
  "scope":"https://mail.google.com/"
}

SASL 协议要求客户端向此质询发送空响应。

IMAP 协议交换

本部分介绍了如何将 SASL XOAUTH2 与 Gmail IMAP 服务器搭配使用。

初始客户端响应

如需使用 SASL XOAUTH2 机制登录，客户端会调用 AUTHENTICATE 命令，其中包含 XOAUTH2 机制参数和上述构建的初始客户端响应。例如：

[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2 AUTH=XOAUTH
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvb
QFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG
1semRHRXVZMjl0Q2cBAQ==
S: A01 OK Success
[connection continues...]

关于 IMAP 协议交换，请注意以下事项：

  • IMAP AUTHENTICATE 命令记录在 RFC 3501 中。
  • 借助 SASL-IR 功能，您可以在 AUTHENTICATE 命令的第一行中发送初始客户端响应，这样只需一次往返即可进行身份验证。SASL-IR 记录在 RFC 4959 中。
  • AUTH=XOAUTH2 功能声明服务器支持本文档定义的 SASL 机制，并且通过将 XOAUTH2 指定为 AUTHENTICATE 命令的第一个实参来激活此机制。
  • AUTHENTICATE 和 CAPABILITY 命令中的换行符是为了清晰起见，实际命令数据中不会出现这些换行符。整个 base64 实参应是一个连续的字符串，不包含嵌入的空格，这样整个 AUTHENTICATE 命令就由一行文本组成。

错误响应

身份验证失败也会通过 IMAP AUTHENTICATE 命令返回：

[connection begins]
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQ
FhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1s
emRHRXVZMjl0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: A01 NO SASL authentication failed

关于 IMAP 协议交换，请注意以下事项：

  • 客户端会向包含错误消息的质询发送空响应（“\r\n”）。

POP 协议交换

本部分介绍了如何将 SASL XOAUTH2 与 Gmail POP 服务器搭配使用。

初始客户端响应

如需使用 SASL XOAUTH2 机制登录，客户端会调用 AUTH 命令，其中包含 XOAUTH2 机制参数和上述构建的初始客户端响应。例如：

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]

关于 POP 协议交换，请注意以下事项：

  • POP AUTH 命令记录在 RFC 1734 中。
  • AUTH 命令中的换行符是为了清晰起见，实际命令数据中不会出现这些换行符。整个 base64 实参应是一个连续的字符串，不包含嵌入的空格，这样整个 AUTH 命令就由一行文本组成。

错误响应

身份验证失败也会通过 POP AUTH 命令返回：

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==

SMTP 协议交换

本部分介绍了如何将 SASL XOAUTH2 与 Gmail SMTP 服务器搭配使用。

初始客户端响应

如需使用 XOAUTH2 机制登录，客户端会调用 AUTH 命令，其中包含 XOAUTH2 机制参数和上述构建的初始客户端响应。例如：

[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Accepted
[connection continues...]

关于 SMTP 协议交换，请注意以下事项：

  • SMTP AUTH 命令记录在 RFC 4954 中。
  • AUTH 命令中的换行符是为了清晰起见，实际命令数据中不会出现这些换行符。整个 base64 实参应是一个连续的字符串，不包含嵌入的空格，这样整个 AUTH 命令就由一行文本组成。

错误响应

身份验证失败也会通过 SMTP AUTH 命令返回：

[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJl
ciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cB
AQ==
S: 334 eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: 535-5.7.1 Username and Password not accepted. Learn more at
S: 535 5.7.1 https://support.google.com/mail/?p=BadCredentials hx9sm5317360pbc.68
[connection continues...]

关于 SMTP 协议交换，请注意以下事项：

  • 客户端会向包含错误消息的质询发送空响应（“\r\n”）。

参考