OAuth 2.0 機制

本文件定義了可與 IMAP AUTHENTICATE、POP AUTH 和 SMTP AUTH 指令搭配使用的 SASL XOAUTH2 機制。此機制可使用 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 連線的行為會有所不同：

  • 即使使用者已在 Gmail 設定中停用了 [在 IMAP 中顯示] 標籤，系統仍會透過 IMAP 顯示所有標籤。
  • 無論使用者在 Gmail 設定 [資料夾大小限制] 中設定的內容為何，都會透過 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 指令的第一行傳送初始用戶端回應，因此驗證只需要一次來回。SA 4959 記錄了 SASL-IR。
  • 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 通訊協定交換

本節說明如何將 SASL XOAUTH2 與 Gmail SMTP 伺服器搭配使用。

初次客戶回應

如要使用 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」)。

參考資料