Mekanisme OAuth 2.0

Dokumen ini menentukan mekanisme SASL XOAUTH2 untuk digunakan dengan perintah IMAP AUTHENTICATE, POP AUTH, dan SMTP AUTH. Mekanisme ini memungkinkan penggunaan Token Akses OAuth 2.0 untuk mengautentikasi ke akun Gmail pengguna.

Menggunakan OAuth 2.0

Mulailah dengan memahami Menggunakan OAuth 2.0 untuk Mengakses Google API. Dokumen tersebut menjelaskan cara kerja OAuth 2.0, dan langkah-langkah yang diperlukan untuk menulis klien.

Anda juga dapat menjelajahi contoh kode XOAUTH2 untuk melihat contoh yang berfungsi.

Cakupan OAuth 2.0

Cakupan untuk akses IMAP, POP, dan SMTP adalah https://mail.google.com/. Jika Anda meminta akses ke cakupan email lengkap untuk aplikasi IMAP, POP, atau SMTP, aplikasi tersebut harus mematuhi Layanan Google API: Kebijakan Data Pengguna kami.

  • Agar disetujui, aplikasi Anda harus menunjukkan penggunaan penuh https://mail.google.com/.
  • Jika aplikasi Anda tidak memerlukan https://mail.google.com/, bermigrasilah ke Gmail API dan gunakan cakupan terbatas yang lebih terperinci.

Delegasi tingkat domain untuk Google Workspace

Jika Anda ingin menggunakan Google Workspace delegasi seluruh domain menggunakan Akun Layanan untuk mengakses kotak surat pengguna Google Workspace melalui IMAP, Anda dapat memberi otorisasi klien menggunakan cakupan https://www.googleapis.com/auth/gmail.imap_admin.

Jika diberi otorisasi dengan cakupan ini, koneksi IMAP akan berperilaku berbeda:

  • Semua label ditampilkan melalui IMAP, meskipun pengguna menonaktifkan "Tampilkan di IMAP" untuk label di setelan Gmail.
  • Semua pesan ditampilkan melalui IMAP, terlepas dari apa yang ditetapkan pengguna di "Batas Ukuran Folder" di setelan Gmail.

Mekanisme SASL XOAUTH2

Mekanisme XOAUTH2 memungkinkan klien mengirim token akses OAuth 2.0 ke server. Protokol ini menggunakan nilai yang dienkode yang ditampilkan di bagian berikut.

Respons Klien Awal

Respons klien awal SASL XOAUTH2 memiliki format berikut:

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

Gunakan mekanisme encoding base64 yang ditentukan dalam RFC 4648. ^A mewakili Control+A (\001).

Misalnya, sebelum encoding base64, respons klien awal mungkin terlihat seperti ini:

user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A

Setelah encoding base64, ini menjadi (jeda baris disisipkan untuk kejelasan):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Respons Error

Respons klien awal yang menyebabkan error akan membuat server mengirim tantangan yang berisi pesan error dalam format berikut:

base64({JSON-Body})

JSON-Body berisi tiga nilai: status, schemes, dan scope. Contoh:

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

Setelah dekode base64, ini menjadi (diformat untuk kejelasan):

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

Protokol SASL mengharuskan klien mengirim respons kosong ke tantangan ini.

Pertukaran Protokol IMAP

Bagian ini menjelaskan cara menggunakan SASL XOAUTH2 dengan server IMAP Gmail.

Respons Klien Awal

Untuk login dengan mekanisme SASL XOAUTH2, klien memanggil perintah AUTHENTICATE dengan parameter mekanisme XOAUTH2, dan respons klien awal seperti yang dibuat di atas. Contoh:

[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...]

Hal-hal yang perlu diperhatikan tentang pertukaran protokol IMAP:

  • Perintah AUTHENTICATE IMAP didokumentasikan dalam RFC 3501.
  • Kemampuan SASL-IR memungkinkan pengiriman respons klien awal di baris pertama perintah AUTHENTICATE, sehingga hanya diperlukan satu perjalanan bolak-balik untuk autentikasi. SASL-IR didokumentasikan dalam RFC 4959.
  • Kemampuan AUTH=XOAUTH2 mendeklarasikan bahwa server mendukung mekanisme SASL yang ditentukan oleh dokumen ini, dan mekanisme ini diaktifkan dengan menentukan XOAUTH2 sebagai argumen pertama ke perintah AUTHENTICATE.
  • Pemisah baris dalam perintah AUTHENTICATE dan CAPABILITY dimaksudkan untuk kejelasan dan tidak akan ada dalam data perintah yang sebenarnya. Seluruh argumen base64 harus berupa satu string berkelanjutan, tanpa spasi kosong yang disematkan, sehingga seluruh perintah AUTHENTICATE terdiri dari satu baris teks.

Respons Error

Kegagalan autentikasi juga ditampilkan melalui perintah AUTHENTICATE 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

Hal-hal yang perlu diperhatikan tentang pertukaran protokol IMAP:

  • Klien mengirim respons kosong ("\r\n") ke tantangan yang berisi pesan error.

POP Protocol Exchange

Bagian ini menjelaskan cara menggunakan SASL XOAUTH2 dengan server POP Gmail.

Respons Klien Awal

Untuk login dengan mekanisme SASL XOAUTH2, klien memanggil perintah AUTH dengan parameter mekanisme XOAUTH2, dan respons klien awal seperti yang dibuat di atas. Contoh:

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]

Hal-hal yang perlu diperhatikan tentang pertukaran protokol POP:

  • Perintah POP AUTH didokumentasikan dalam RFC 1734.
  • Pemisah baris dalam perintah AUTH dimaksudkan untuk kejelasan dan tidak akan ada dalam data perintah yang sebenarnya. Seluruh argumen base64 harus berupa satu string berkelanjutan, tanpa spasi kosong yang disematkan, sehingga seluruh perintah AUTH terdiri dari satu baris teks.

Respons Error

Kegagalan autentikasi juga ditampilkan melalui perintah POP AUTH:

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

Pertukaran Protokol SMTP

Bagian ini menjelaskan cara menggunakan SASL XOAUTH2 dengan server SMTP Gmail.

Respons Klien Awal

Untuk login dengan mekanisme XOAUTH2, klien memanggil perintah AUTH dengan parameter mekanisme XOAUTH2, dan respons klien awal seperti yang dibuat di atas. Contoh:

[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...]

Hal-hal yang perlu diperhatikan tentang pertukaran protokol SMTP:

  • Perintah AUTH SMTP didokumentasikan dalam RFC 4954.
  • Pemisah baris dalam perintah AUTH dimaksudkan untuk kejelasan dan tidak akan ada dalam data perintah yang sebenarnya. Seluruh argumen base64 harus berupa satu string berkelanjutan, tanpa spasi kosong yang disematkan, sehingga seluruh perintah AUTH terdiri dari satu baris teks.

Respons Error

Kegagalan autentikasi juga ditampilkan melalui perintah AUTH 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...]

Hal-hal yang perlu diperhatikan tentang pertukaran protokol SMTP:

  • Klien mengirim respons kosong ("\r\n") ke tantangan yang berisi pesan error.

Referensi