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 機制登入，用戶端會叫用 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 機制登入，用戶端會使用 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」) 給含有錯誤訊息的挑戰。

參考資料