Mekanisme OAuth 2.0

Dokumen ini mendefinisikan 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 mempelajari 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 kode XOAUTH2 contoh 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 penuh untuk aplikasi IMAP, POP, atau SMTP Anda, aplikasi tersebut harus mematuhi Layanan API Google: 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/, bermigrasilah ke Gmail API dan gunakan cakupan terbatas yang lebih terperinci.

Delegasi tingkat domain untuk Google Workspace

Jika Anda ingin menggunakan delegasi tingkat domain Google Workspace menggunakan Akun Layanan untuk mengakses kotak surat pengguna Google Workspace melalui IMAP, Anda dapat memberikan otorisasi pada 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 Awal Klien

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 dienkode base64, respons klien awal mungkin terlihat seperti ini:

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

Setelah dienkode base64, ini akan menjadi (pemisah baris dimasukkan untuk kejelasan):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Respons Error

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

base64({JSON-Body})

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

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

Setelah didekode base64, ini akan menjadi (diformat agar lebih jelas):

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

Protokol SASL mengharuskan klien mengirim respons kosong untuk tantangan ini.

Exchange Protokol IMAP

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

Respons Awal Klien

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 IMAP AUTHENTICATE didokumentasikan dalam RFC 3501.
  • Kemampuan SASL-IR memungkinkan pengiriman respons klien awal di baris pertama perintah AUTHENTICATE, sehingga hanya diperlukan satu perjalanan pulang pergi 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 untuk perintah AUTHENTICATE.
  • Pecahan baris dalam perintah AUTHENTICATE dan CAPABILITY ditambahkan untuk memperjelas dan tidak akan ada dalam data perintah 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 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

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 Awal Klien

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.
  • Pemisahan baris dalam perintah AUTH dilakukan untuk memperjelas dan tidak akan ada dalam data perintah 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 Awal Klien

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 SMTP AUTH didokumentasikan dalam RFC 4954.
  • Pemisahan baris dalam perintah AUTH dilakukan untuk memperjelas dan tidak akan ada dalam data perintah 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 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...]

Hal-hal yang perlu diperhatikan tentang pertukaran protokol SMTP:

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

Referensi