Español – América Latina Português – Brasil Google Workspace 本文档定义了 SASL XOAUTH2 机制，以用于 IMAP AUTHENTICATE 、POP AUTH 和 SMTP AUTH 命令。此机制允许使用 OAuth 2.0 访问令牌向用户的 Gmail 账号进行身份验证。 首先，请阅读 使用 OAuth 2.0 访问 Google API 。 该文档介绍了 OAuth 2.0 的工作原理，以及编写客户端所需的步骤。 您还可以浏览 示例 XOAUTH2 代码 ，了解实际示例。 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 初始客户端响应的格式如下： 使用 RFC 4648 中定义的 base64 编码机制。 ^A 表示 Control+A (\001)。 例如，在进行 base64 编码之前，初始客户端响应可能如下所示： 经过 base64 编码后，此字符串变为（为清晰起见，我们插入了换行符）： 如果初始客户端响应导致错误，服务器会发送一条包含错误消息的质询，格式如下： JSON-Body 包含三个值： status 、 schemes 和 scope 。例如： 经过 base64 解码后，此字符串变为（为清晰起见，已进行格式化）： SASL 协议要求客户端针对此质询发送空响应。 本部分介绍了如何将 SASL XOAUTH2 与 Gmail IMAP 服务器搭配使用。 如需使用 SASL XOAUTH2 机制登录，客户端会调用 AUTHENTICATE 命令，并将机制参数设置为 XOAUTH2 ，并使用之前构建的初始客户端响应。例如： 有关 IMAP 协议交换，请注意以下事项： IMAP AUTHENTICATE 命令的文档位于 RFC 3501 中。 SASL-IR 功能允许在 AUTHENTICATE 命令的第一行中发送初始客户端响应，这样只需一次往返即可完成身份验证。SASL-IR 的相关文档请参阅 RFC 4959 。 AUTH=XOAUTH2 功能声明服务器支持本文档定义的 SASL 机制，并且通过将 XOAUTH2 指定为 AUTHENTICATE 命令的第一个实参来激活此机制。

AUTHENTICATE 和 CAPABILITY 命令中的换行符是为了清晰起见，实际命令数据中没有这些换行符。整个 base64 实参应是一个连续的字符串，不含嵌入的空格，这样整个 AUTHENTICATE 命令就由一行文本组成。 身份验证失败也会通过 IMAP AUTHENTICATE 命令返回： 有关 IMAP 协议交换，请注意以下事项： 客户端向包含错误消息的质询发送空响应（“\r\n”）。 本部分介绍了如何将 SASL XOAUTH2 与 Gmail POP 服务器搭配使用。 如需使用 SASL XOAUTH2 机制登录，客户端会调用 AUTH 命令，并将机制参数设置为 XOAUTH2 ，并使用之前构建的初始客户端响应。例如： 关于 POP 协议交换的注意事项： POP AUTH 命令的文档位于 RFC 1734 中。 AUTH 命令中的换行符是为了清晰起见，实际命令数据中没有这些换行符。整个 base64 实参应为一个连续的字符串，不含嵌入的空格，以便整个 AUTH 命令由单行文本组成。 身份验证失败也会通过 POP AUTH 命令返回： 本部分介绍了如何将 SASL XOAUTH2 与 Gmail SMTP 服务器搭配使用。 如需使用 XOAUTH2 机制登录，客户端会调用 AUTH 命令，并将机制参数设置为 XOAUTH2 ，并将初始客户端响应设置为之前构建的响应。例如： 关于 SMTP 协议交换，请注意以下事项： SMTP AUTH 命令记录在 RFC 4954 中。 AUTH 命令中的换行符是为了清晰起见，实际命令数据中没有这些换行符。整个 base64 实参应为一个连续的字符串，不含嵌入的空格，以便整个 AUTH 命令由单行文本组成。 身份验证失败也会通过 SMTP AUTH 命令返回： 关于 SMTP 协议交换，请注意以下事项： 客户端向包含错误消息的质询发送空响应（“\r\n”）。 OAUTH2： 使用 OAuth 2.0 访问 Google API SMTP： RFC 2821：简单邮件传输协议 IMAP： RFC 3501：INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1（互联网邮件访问协议 - 版本 4rev1） POP： RFC 1081：邮局协议 - 版本 3 SASL： RFC 4422：简单身份验证和安全层 (SASL) JSON： RFC 4627：JavaScript 对象表示法的 application/json 媒体类型 BASE64： RFC 4648：Base16、Base32 和 Base64 数据编码 SASL-IR： RFC 4959：简单身份验证和安全层 (SASL) 初始客户端响应的 IMAP 扩展 SMTP-AUTH： RFC 4954：用于身份验证的 SMTP 服务扩展 如未另行说明，那么本页面中的内容已根据 知识共享署名 4.0 许可 获得了许可，并且代码示例已根据 Apache 2.0 许可 获得了许可。有关详情，请参阅 Google 开发者网站政策 。Java 是 Oracle 和/或其关联公司的注册商标。 最后更新时间 (UTC)：2026-09-17。