Mekanisme OAuth 2.0

Dokumen ini menjelaskan mekanisme SASL XOAUTH2 untuk digunakan dengan perintah IMAP AUTHENTICATE, POP AUTH, dan SMTP AUTH. Mekanisme ini memungkinkan penggunaan Token Akses OAuth 2.0 untuk melakukan autentikasi 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 melihat contoh kode XOAUTH2 untuk mengetahui 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 https://mail.google.com/ secara penuh.
  • Jika aplikasi Anda tidak memerlukan https://mail.google.com/, migrasikan ke Gmail API dan gunakan cakupan terbatas yang lebih terperinci.

Delegasi tingkat domain untuk Google Workspace

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

Jika diizinkan 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 setelan yang ditetapkan pengguna di "Batas Ukuran Folder" di setelan Gmail.

Mekanisme SASL XOAUTH2

Mekanisme XOAUTH2 memungkinkan klien untuk mengirim token akses OAuth 2.0 ke server. Protokol 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 merepresentasikan 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 agar lebih jelas):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Respons Error

Respons klien awal yang menyebabkan error akan menyebabkan 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 decoding base64, parameter ini menjadi (diformat untuk kejelasan):

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

Protokol SASL mengharuskan klien untuk mengirim respons kosong terhadap 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 satu perjalanan dua arah yang diperlukan untuk autentikasi. SASL-IR didokumentasikan dalam RFC 4959.
  • Kemampuan AUTH=XOAUTH2 menyatakan bahwa server mendukung mekanisme SASL yang ditentukan oleh dokumen ini, dan mekanisme ini diaktifkan dengan menentukan XOAUTH2 sebagai argumen pertama dari perintah AUTHENTICATE.
  • Jeda baris dalam perintah AUTHENTICATE dan CAPABILITY ditujukan agar lebih jelas dan tidak akan ada dalam data perintah yang sebenarnya. Seluruh argumen base64 harus berupa satu string berkelanjutan, tanpa spasi kosong tersemat, 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.

Pertukaran Protokol POP

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 AUTH POP didokumentasikan dalam RFC 1734.
  • Jeda baris dalam perintah AUTH ditujukan agar lebih jelas dan tidak akan ada dalam data perintah yang sebenarnya. Seluruh argumen base64 harus berupa satu string berkelanjutan, tanpa spasi kosong tersemat, 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==

SMTP Protocol Exchange

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.
  • Jeda baris dalam perintah AUTH ditujukan agar lebih jelas dan tidak akan ada dalam data perintah yang sebenarnya. Seluruh argumen base64 harus berupa satu string berkelanjutan, tanpa spasi kosong tersemat, 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