Tài liệu này xác định cơ chế SASL XOAUTH2 để sử dụng với các lệnh IMAP AUTHENTICATE
, POP AUTH
và SMTP AUTH
. Cơ chế này cho phép sử dụng Mã truy cập OAuth 2.0 để xác thực tài khoản Gmail của người dùng.
Sử dụng OAuth 2.0
Hãy bắt đầu bằng cách tự làm quen với việc Sử dụng OAuth 2.0 để truy cập API Google. Tài liệu đó giải thích cách hoạt động của OAuth 2.0 và các bước cần thực hiện để viết một ứng dụng.
Bạn cũng có thể duyệt xem mã XOAUTH2 mẫu để xem các ví dụ về cách làm việc.
Phạm vi OAuth 2.0
Phạm vi truy cập IMAP, POP và SMTP là https://mail.google.com/
. Nếu bạn yêu cầu quyền truy cập vào toàn bộ phạm vi thư cho ứng dụng IMAP, POP hoặc SMTP của mình, thì ứng dụng đó phải tuân thủ Chính sách dữ liệu người dùng trong Dịch vụ API của Google.
- Để được phê duyệt, ứng dụng của bạn phải cho thấy hiệu suất sử dụng tối đa
https://mail.google.com/
. - Nếu ứng dụng của bạn không yêu cầu
https://mail.google.com/
, hãy chuyển sang API Gmail và sử dụng phạm vi bị hạn chế chi tiết hơn.
Uỷ quyền trên toàn miền cho Google Workspace
Nếu định sử dụng tính năng Google Workspace uỷ quyền trên toàn miền bằng Tài khoản dịch vụ để truy cập vào Google Workspace hộp thư của người dùng qua IMAP, thì bạn có thể uỷ quyền cho ứng dụng khách bằng phạm vi https://www.googleapis.com/auth/gmail.imap_admin
.
Khi được uỷ quyền với phạm vi này, các kết nối IMAP sẽ hoạt động theo cách khác:
- Tất cả các nhãn được hiển thị qua IMAP, ngay cả khi người dùng đã tắt chế độ "Hiển thị trong IMAP" cho nhãn trong phần cài đặt của Gmail.
- Tất cả thư được hiển thị qua IMAP, bất kể người dùng đặt trong "Giới hạn kích thước thư mục" trong phần cài đặt Gmail là gì.
Cơ chế SASL XOAUTH2
Cơ chế XOAUTH2 cho phép ứng dụng gửi mã truy cập OAuth 2.0 tới máy chủ. Giao thức sử dụng các giá trị đã mã hoá như trong các phần sau.
Phản hồi ban đầu của khách hàng
Phản hồi ban đầu của ứng dụng SASL XOAUTH2 có định dạng sau:
base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")
Sử dụng cơ chế mã hoá base64 được xác định trong RFC 4648. ^A
đại diện cho tổ hợp phím Control + A (\001).
Ví dụ: trước khi mã hoá base64, phản hồi ban đầu của ứng dụng có thể có dạng như sau:
user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A
Sau khi mã hoá base64, đoạn mã này sẽ trở thành (chèn ngắt dòng cho rõ ràng):
dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
Phản hồi lỗi
Phản hồi ban đầu của ứng dụng gây ra lỗi sẽ dẫn đến việc máy chủ gửi một thách thức chứa thông báo lỗi ở định dạng sau:
base64({JSON-Body})
JSON-Body chứa ba giá trị: status
, schemes
và scope
. Ví dụ:
eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K
Sau khi giải mã base64, giá trị này sẽ trở thành (được định dạng cho rõ ràng):
{
"status":"401",
"schemes":"bearer",
"scope":"https://mail.google.com/"
}
Giao thức SASL yêu cầu ứng dụng gửi một phản hồi trống cho thử thách này.
Trao đổi giao thức IMAP
Phần này giải thích cách sử dụng SASL XOAUTH2 với máy chủ IMAP của Gmail.
Phản hồi ban đầu của khách hàng
Để đăng nhập bằng cơ chế SASL XOAUTH2, ứng dụng sẽ gọi lệnh AUTHENTICATE
với tham số cơ chế là XOAUTH2
và phản hồi ban đầu của ứng dụng như đã tạo ở trên. Ví dụ:
[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...]
Những điều cần lưu ý về việc trao đổi giao thức IMAP:
- Lệnh
AUTHENTICATE
của IMAP được ghi lại trong RFC 3501. - Tính năng SASL-IR cho phép gửi phản hồi ban đầu của ứng dụng ở dòng đầu tiên của lệnh
AUTHENTICATE
, nhờ vậy, chỉ cần một lượt khứ hồi để xác thực. SASL-IR được ghi lại trong RFC 4959. - Tính năng AUTH=XOAUTH2 khai báo rằng máy chủ hỗ trợ cơ chế SASL được xác định trong tài liệu này và cơ chế này được kích hoạt bằng cách chỉ định XOAUTH2 làm đối số đầu tiên cho lệnh
AUTHENTICATE
. - Dấu ngắt dòng trong các lệnh
AUTHENTICATE
vàCAPABILITY
có mục đích rõ ràng và sẽ không xuất hiện trong dữ liệu lệnh thực tế. Toàn bộ đối số base64 phải là một chuỗi liên tục, không có khoảng trắng được nhúng để toàn bộ lệnhAUTHENTICATE
bao gồm một dòng văn bản duy nhất.
Phản hồi lỗi
Lỗi xác thực cũng được trả về qua lệnh AUTHENTICATE
của IMAP:
[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
Những điều cần lưu ý về việc trao đổi giao thức IMAP:
- Máy khách gửi một phản hồi trống ("\r\n") đến hình ảnh xác thực có chứa thông báo lỗi.
Trao đổi giao thức POP
Phần này giải thích cách sử dụng SASL XOAUTH2 với máy chủ POP của Gmail.
Phản hồi ban đầu của khách hàng
Để đăng nhập bằng cơ chế SASL XOAUTH2, ứng dụng sẽ gọi lệnh AUTH
với tham số cơ chế là XOAUTH2
và phản hồi ban đầu của ứng dụng như đã tạo ở trên. Ví dụ:
[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]
Những điều cần lưu ý về trao đổi giao thức POP:
- Lệnh POP
AUTH
được ghi lại trong RFC 1734. - Ngắt dòng trong lệnh
AUTH
nhằm mục đích rõ ràng và sẽ không xuất hiện trong dữ liệu lệnh thực tế. Toàn bộ đối số base64 phải là một chuỗi liên tục, không có khoảng trắng được nhúng để toàn bộ lệnhAUTH
bao gồm một dòng văn bản duy nhất.
Phản hồi lỗi
Lỗi xác thực cũng được trả về qua lệnh POP AUTH
:
[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==
Trao đổi giao thức SMTP
Phần này giải thích cách sử dụng SASL XOAUTH2 với máy chủ SMTP của Gmail.
Phản hồi ban đầu của khách hàng
Để đăng nhập bằng cơ chế XOAUTH2, ứng dụng sẽ gọi lệnh AUTH
với tham số cơ chế là XOAUTH2
và phản hồi ban đầu của ứng dụng như đã tạo ở trên. Ví dụ:
[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...]
Những điều cần lưu ý về việc trao đổi giao thức SMTP:
- Lệnh
AUTH
của SMTP được ghi lại trong RFC 4954. - Ngắt dòng trong lệnh
AUTH
nhằm mục đích rõ ràng và sẽ không xuất hiện trong dữ liệu lệnh thực tế. Toàn bộ đối số base64 phải là một chuỗi liên tục, không có khoảng trắng được nhúng để toàn bộ lệnhAUTH
bao gồm một dòng văn bản duy nhất.
Phản hồi lỗi
Lỗi xác thực cũng được trả về qua lệnh AUTH
của SMTP:
[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...]
Những điều cần lưu ý về việc trao đổi giao thức SMTP:
- Máy khách gửi một phản hồi trống ("\r\n") đến hình ảnh xác thực có chứa thông báo lỗi.
Tài liệu tham khảo
- OAUTH2: Sử dụng OAuth 2.0 để truy cập vào các API của Google
- SMTP: RFC 2821: Simple Mail Transfer Protocol (Giao thức truyền thư đơn giản)
- IMAP: RFC 3501: TÀI LIỆU TRUY CẬP THÔNG TIN InterNET - PHIÊN BẢN 4rev1
- POP: RFC 1081: Post Office Protocol – Phiên bản 3
- SASL: RFC 4422: Lớp bảo mật và xác thực đơn giản (SASL)
- JSON: RFC 4627: The application/json Media Type for JavaScript Object Notation (Loại phương tiện ứng dụng/json để ghi đối tượng JavaScript):
- BASE64: RFC 4648: Mã hoá dữ liệu Base16, Base32 và Base64
- SASL-IR: RFC 4959: Tiện ích IMAP cho phản hồi ban đầu của ứng dụng ở tầng bảo mật và xác thực đơn giản (SASL)
- SMTP-AUTH: RFC 4954: Tiện ích dịch vụ SMTP để xác thực