OAuth 2.0 機制

本文件定義了與 IMAP 搭配使用的 SASL XOAUTH2 機制 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 全網域委派 使用 服務帳戶 存取 Google Workspace 使用者透過 IMAP 存取郵件 您可以授予用戶端存取權 https://www.googleapis.com/auth/gmail.imap_admin。

在這個範圍授權的情況下，IMAP 連線的運作方式會有所不同：

  • 所有標籤都透過 IMAP 顯示，即使使用者停用「在 IMAP 中顯示」設定。
  • 不論使用者在「資料夾大小限制」中設定什麼，所有郵件都會透過 IMAP 顯示。

SASL XOAUTH2 機制

XOAUTH2 機制可讓用戶端將 OAuth 2.0 存取權杖傳送至伺服器。此通訊協定使用以下各節所示的編碼值。

初步客戶回應

SASL XOAUTH2 初始用戶端回應採用以下格式：

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

使用 RFC 4648 中定義的 Base64 編碼機制。^A 代表 Control + 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 機制登入，用戶端會使用 XOAUTH2 的機制參數叫用 AUTHENTICATE 指令，以及如上建構的初始用戶端回應。例如：

[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 機制登入，用戶端會使用 XOAUTH2 的機制參數叫用 AUTH 指令，以及如上建構的初始用戶端回應。例如：

[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 通訊協定交換

本節說明如何在 Gmail SMTP 伺服器中使用 SASL XOAUTH2。

初步客戶回應

如要使用 XOAUTH2 機制登入，用戶端會使用 XOAUTH2 的機制參數和初始用戶端回應 (如上文所述) 叫用 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 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」)。

參考資料