本文件定義 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 包含三個值:status
、schemes
和 scope
。例如:
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
指令的第一個引數,藉此啟用此機制。 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 通訊協定交換的注意事項:
- 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"),其中包含錯誤訊息。
參考資料
- OAUTH2:使用 OAuth 2.0 存取 Google API
- SMTP:RFC 2821:簡易郵件傳輸通訊協定
- IMAP:RFC 3501:INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1
- POP:RFC 1081:Post Office Protocol - Version 3
- SASL:RFC 4422:簡易驗證和安全性層 (SASL)
- JSON:RFC 4627:JavaScript 物件標記法的 application/json 媒體類型
- BASE64:RFC 4648:Base16、Base32 和 Base64 資料編碼
- SASL-IR:RFC 4959:IMAP 擴充功能,適用於簡易驗證和安全性層 (SASL) 的初始用戶端回應
- SMTP-AUTH:RFC 4954:用於驗證的 SMTP 服務擴充功能