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 網域範圍的委派，透過服務帳戶存取 Google Workspace 使用者的 IMAP 郵箱，可以改用 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 代表 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 通訊協定交換

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

初始用戶端回應

如要使用 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") 傳送至驗證。

參考資料