Cơ chế OAuth 2.0

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 vào 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ìm hiểu về việc sử dụng OAuth 2.0 để truy cập vào các API của 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 thiết để 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ụ minh hoạ.

Phạm vi OAuth 2.0

Phạm vi truy cập cho 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, thì ứng dụng đó phải tuân thủ Chính sách dữ liệu người dùng của các dịch vụ API của Google.

  • Để được phê duyệt, ứng dụng của bạn phải cho thấy việc sử dụng đầy đủ https://mail.google.com/.
  • Nếu ứng dụng của bạn không cần https://mail.google.com/, hãy di chuyển sang API Gmail và sử dụng các phạm vi bị hạn chế chi tiết hơn.

Uỷ quyền trên toàn miền đối với Google Workspace

Nếu dự định sử dụng cơ chế uỷ quyền trên toàn miền Google Workspace bằng tài khoản dịch vụ để truy cập vào hộp thư của người dùng Google Workspace thông qua IMAP, thì bạn có thể uỷ quyền cho ứng dụng bằng phạm vi https://www.googleapis.com/auth/gmail.imap_admin.

Khi được uỷ quyền bằng phạm vi này, các kết nối IMAP sẽ hoạt động theo cách khác:

  • Tất cả nhãn đều xuất hiện 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 Gmail.
  • Tất cả thư đều xuất hiện qua IMAP, bất kể người dùng đặt chế độ nào trong phần "Giới hạn kích thước thư mục" trong phần cài đặt Gmail.

Cơ chế SASL XOAUTH2

Cơ chế XOAUTH2 cho phép các ứng dụng gửi mã truy cập OAuth 2.0 đến máy chủ. Giao thức này sử dụng các giá trị được mã hoá như trong các phần sau.

Phản hồi ban đầu của ứng dụng

Phản hồi ban đầu của ứng dụng SASL XOAUTH2 có định dạng như sau:

base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")

Sử dụng cơ chế mã hoá base64 theo định nghĩa trong tiêu chuẩn RFC 4648. ^A biểu thị Ctrl+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, phản hồi này sẽ trở thành (các dấu ngắt dòng được chèn vào để 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 khiến máy chủ gửi một thử thách chứa thông báo lỗi theo định dạng sau:

base64({JSON-Body})

JSON-Body chứa 3 giá trị: status, schemes và scope. Ví dụ:

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

Sau khi giải mã base64, mã 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 ứng dụ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 sẽ giống như đã nêu ở 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 qua giao thức IMAP:

  • Lệnh IMAP AUTHENTICATE được ghi trong tài liệu RFC 3501.
  • Chức 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 để chỉ cần một gửi dữ liệu đi một vòng để xác thực. SASL-IR được ghi trong tài liệu RFC 4959.
  • Chức năng AUTH=XOAUTH2 khai báo rằng máy chủ hỗ trợ cơ chế SASL theo định nghĩa của 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.
  • Các dấu ngắt dòng trong lệnh AUTHENTICATE và CAPABILITY là để cho 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ệnh AUTHENTICATE 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ề thông qua lệnh 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

Những điều cần lưu ý về việc trao đổi qua giao thức IMAP:

  • Ứng dụng gửi một phản hồi trống ("\r\n") đến thử thách có chứa thông báo lỗi.

Trao đổi qua 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 ứng dụng

Để đăng nhập bằng cơ chế SASL XOAUTH2, máy khách sẽ gọi lệnh AUTH với tham số cơ chế là XOAUTH2 và phản hồi ban đầu của máy khách sẽ giống như đã nêu ở 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ề việc trao đổi qua giao thức POP:

  • Lệnh POP AUTH được ghi lại trong tài liệu RFC 1734.
  • Các dấu ngắt dòng trong lệnh AUTH là để cho 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ệnh AUTH 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ề thông qua lệnh POP AUTH:

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==

Trao đổi qua 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 ứng dụ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 giống như đã nêu ở 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 qua giao thức SMTP:

  • Lệnh SMTP AUTH được ghi trong tài liệu RFC 4954.
  • Các dấu ngắt dòng trong lệnh AUTH là để cho 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ệnh AUTH 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ề thông qua lệnh 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...]

Những điều cần lưu ý về việc trao đổi qua giao thức SMTP:

  • Ứng dụng gửi một phản hồi trống ("\r\n") đến thử thách có chứa thông báo lỗi.

Tài liệu tham khảo