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 全網域委派功能，透過 IMAP 存取使用者的信箱，請改用範圍 https://www.googleapis.com/auth/gmail.imap_admin 授權用戶端。 Google Workspace

在這個範圍授權的情況下，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 指令的第一行傳送初始用戶端回應，因此驗證只需要一次來回傳輸。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 通訊協定交換

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

初步客戶回應

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

參考資料