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,並使用更精細的受限制範圍

的全網域委派

如果您想使用服務帳戶 全網域委派功能,透過 IMAP 存取使用者的信箱,請改用範圍 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 包含三個值:statusschemesscope。例如:

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

經過 base64 解碼後,會變成以下格式 (為了方便說明,我們已調整格式):

{
  "status":"401",
  "schemes":"bearer",
  "scope":"https://mail.google.com/"
}

SASL 通訊協定要求用戶端針對此驗證方法傳送空白回應。

IMAP 通訊協定交換

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

初始用戶端回應

如要使用 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 指令的第一行傳送初始用戶端回應,因此驗證只需要一次來回傳輸。RFC 4959 文件中說明瞭 SASL-IR。
  • AUTH=XOAUTH2 功能會宣告伺服器支援本文件定義的 SASL 機制,並指定 XOAUTH2 做為 AUTHENTICATE 指令的第一個引數,藉此啟用此機制。
  • AUTHENTICATECAPABILITY 指令中的換行符號只是為了方便說明,不會出現在實際指令資料中。整個 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 通訊協定交換的注意事項:

  • RFC 1734 文件中說明瞭 POP AUTH 指令。
  • 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"),其中包含錯誤訊息。

參考資料