Otentikasi dan otorisasi adalah mekanisme yang digunakan untuk memverifikasi identitas dan akses ke sumber daya. Dokumen ini menguraikan cara kerja autentikasi dan otorisasi untuk aplikasi Chat dan permintaan Chat API.
Ringkasan proses
Diagram berikut menunjukkan langkah-langkah tingkat tinggi otentikasi dan otorisasi untuk Google Chat:
Konfigurasi project Google Cloud, aktifkan Chat API, dan konfigurasikan aplikasi Chat: Selama pengembangan, Anda membuat project Google Cloud. Di project Google Cloud, Anda mengaktifkan Chat API, mengonfigurasi aplikasi Chat Anda, dan menyiapkan autentikasi. Untuk mengetahui informasi selengkapnya, lihat Mengembangkan di Google Workspace dan Mem-build aplikasi Chat.
Memanggil Chat API: Saat aplikasi Anda memanggil Chat API, aplikasi akan mengirimkan kredensial autentikasi ke Chat API. Jika aplikasi Anda melakukan otentikasi dengan akun layanan, kredensial akan dikirim sebagai pada kode aplikasi Anda. Jika aplikasi Anda perlu memanggil Chat API menggunakan otentikasi pengguna yang belum diberikan, maka akan meminta untuk login.
Minta resource: Aplikasi Anda meminta akses dengan cakupan yang Anda tentukan saat menyiapkan otentikasi.
Minta izin: Jika aplikasi Anda diautentikasi sebagai pengguna, Google akan menampilkan layar izin OAuth sehingga pengguna dapat memutuskan apakah akan memberikan aplikasi Anda atau tidak akses ke data yang diminta. Otentikasi dengan akun layanan tidak memerlukan izin pengguna.
Kirim permintaan fasilitas yang disetujui: Jika pengguna mengizinkan cakupan otorisasi, app bundle Anda, kredensial, dan cakupan ke dalam permintaan. Permintaan dikirim ke server otorisasi Google untuk mendapatkan token akses.
Google menampilkan token akses: Token akses berisi daftar cakupan yang diberikan. Jika daftar cakupan yang ditampilkan lebih membatasi daripada cakupan yang diminta, aplikasi Anda akan menonaktifkan fitur apa pun yang dibatasi oleh token.
Mengakses resource yang diminta: Aplikasi Anda menggunakan token akses dari Google untuk memanggil Chat API dan mengakses resource Chat API.
Dapatkan token refresh (opsional): Jika aplikasi Anda harus mengakses Google Chat API setelah masa berlaku token akses tunggal, dapat memperoleh token refresh. Untuk informasi selengkapnya, lihat Gunakan OAuth 2.0 untuk mengakses Google API.
Minta lebih banyak sumber daya: Jika aplikasi Anda membutuhkan lebih banyak akses, aplikasi akan meminta pengguna untuk melakukannya untuk memberikan cakupan baru, sehingga menghasilkan permintaan baru untuk mendapatkan token akses (langkah 3-6).
Saat aplikasi Chat memerlukan autentikasi
Aplikasi chat dapat mengirim pesan sebagai respons terhadap interaksi pengguna, atau secara asinkron. Mereka juga dapat menyelesaikan tugas atas nama pengguna, seperti membuat ruang Chat atau mendapatkan daftar orang dalam Ruang Chat.
Aplikasi Chat tidak memerlukan autentikasi untuk merespons interaksi pengguna, kecuali jika aplikasi Chat memanggil Chat API atau Google API lainnya saat memproses respons.
Untuk mengirim pesan asinkron atau melakukan tugas atas nama pengguna, Aplikasi chat membuat permintaan RESTful ke Chat API, yang memerlukan otentikasi dan otorisasi.
Respons terhadap interaksi pengguna tidak memerlukan autentikasi
Aplikasi Google Chat tidak perlu melakukan autentikasi sebagai pengguna atau aplikasi Chat untuk menerima dan merespons secara sinkron terhadap peristiwa interaksi.
Aplikasi Google Chat menerima peristiwa interaksi setiap kali pengguna berinteraksi atau memanggil aplikasi Chat, termasuk hal-hal berikut:
- Pengguna mengirim pesan ke aplikasi Chat.
- Pengguna @menyebutkan aplikasi Chat.
- Pengguna memanggil salah satu aplikasi Chat perintah garis miring.
Diagram berikut menunjukkan urutan permintaan-respons antara pengguna Chat dan aplikasi Chat:
- Pengguna mengirim pesan ke aplikasi Chat di Google Chat.
- Google Chat akan meneruskan pesan ke aplikasi.
- Aplikasi menerima pesan, memprosesnya, dan menampilkan respons ke Google Chat.
- Google Chat merender respons untuk pengguna, atau di ruang.
Urutan ini diulang untuk setiap peristiwa interaksi aplikasi Chat.
Pesan asinkron memerlukan autentikasi
Pesan asinkron terjadi saat aplikasi Chat membuat permintaan ke Chat API, yang memerlukan autentikasi dan otorisasi.
Dengan memanggil Chat API, aplikasi Chat dapat memposting pesan ke Google Chat atau menyelesaikan tugas dan mengakses data atas nama pengguna. Misalnya, setelah mendeteksi pemadaman server, aplikasi Chat dapat memanggil Chat API untuk:
- Buat ruang Chat khusus untuk menyelidiki dan memperbaiki pemadaman layanan.
- Tambahkan orang ke ruang Chat.
- Posting pesan ke ruang Chat untuk memberikan detail tentang penghentian layanan.
Diagram berikut menunjukkan urutan pesan asinkron antara Aplikasi Chat dan ruang Chat:
- Aplikasi Chat membuat pesan dengan memanggil
Chat API menggunakan
spaces.messages.createmetode, dan menyertakan kredensial pengguna dalam permintaan HTTP. - Google Chat mengautentikasi aplikasi Chat dengan akun layanan atau kredensial pengguna.
- Google Chat merender pesan aplikasi ke Chat tertentu spasi.
Cakupan Chat API
Mengonfigurasi layar izin OAuth dan memilih cakupan untuk menentukan informasi yang akan ditampilkan kepada pengguna dan peninjau aplikasi, dan mendaftarkan aplikasi Anda sehingga Anda dapat memublikasikannya nanti.
Untuk menentukan tingkat akses yang diberikan ke aplikasi, Anda perlu mengidentifikasi dan mendeklarasikan cakupan otorisasi. Cakupan otorisasi adalah URI OAuth 2.0 string yang berisi nama aplikasi Google Workspace, jenis data yang akses, dan tingkat akses.
Cakupan tidak sensitif
| Kode cakupan | Deskripsi |
|---|---|
https://www.googleapis.com/auth/chat.bot
|
Mengizinkan aplikasi Chat melihat chat dan mengirim pesan. Cakupan ini hanya mendukung autentikasi aplikasi dengan akun layanan. Anda tidak dapat mengotentikasi dengan kredensial pengguna atau dengan delegasi tingkat domain menggunakan cakupan ini. |
Cakupan sensitif
| Kode cakupan | Deskripsi |
|---|---|
https://www.googleapis.com/auth/chat.spaces
|
Membuat percakapan dan ruang serta melihat atau mengedit metadata (termasuk setelan histori dan setelan akses) di Chat. |
https://www.googleapis.com/auth/chat.spaces.create
|
Membuat percakapan baru di Chat. |
https://www.googleapis.com/auth/chat.spaces.readonly
|
Melihat chat dan ruang di Chat. |
https://www.googleapis.com/auth/chat.memberships
|
Melihat, menambahkan, memperbarui, dan menghapus anggota dari percakapan di Chat. |
https://www.googleapis.com/auth/chat.memberships.app
|
Menambahkan dan menghapus dirinya sendiri dari percakapan di Google Chat. |
https://www.googleapis.com/auth/chat.memberships.readonly
|
Melihat anggota dalam percakapan Chat. |
https://www.googleapis.com/auth/chat.messages.create
|
Menulis dan mengirim pesan di Chat. |
https://www.googleapis.com/auth/chat.messages.reactions
|
Melihat, menambahkan, dan menghapus reaksi pada pesan di Chat. |
https://www.googleapis.com/auth/chat.messages.reactions.create
|
Menambahkan reaksi pada pesan di Chat. |
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
Melihat reaksi terhadap pesan di Chat. |
https://www.googleapis.com/auth/chat.users.readstate
|
Melihat dan mengubah waktu baca terakhir untuk percakapan Chat. |
https://www.googleapis.com/auth/chat.users.readstate.readonly
|
Melihat waktu terakhir dibaca untuk percakapan Chat. |
https://www.googleapis.com/auth/chat.admin.spaces.readonly
|
Melihat chat dan ruang yang dimiliki oleh domain administrator di Chat. |
https://www.googleapis.com/auth/chat.admin.spaces
|
Melihat atau mengedit chat dan ruang yang dimiliki oleh domain administrator di Chat. |
https://www.googleapis.com/auth/chat.admin.memberships.readonly
|
Melihat anggota dan pengelola dalam percakapan yang dimiliki oleh domain administrator di Chat. |
https://www.googleapis.com/auth/chat.admin.memberships
|
Melihat, menambahkan, memperbarui, dan menghapus anggota serta pengelola dalam percakapan yang dimiliki oleh domain administrator di Chat. |
https://www.googleapis.com/auth/chat.app.spaces
|
Membuat percakapan dan ruang serta melihat atau memperbarui metadata (termasuk setelan histori dan setelan akses) di Chat. Memerlukan persetujuan administrator. Cakupan ini hanya mendukung autentikasi aplikasi dengan akun layanan. Anda tidak dapat melakukan autentikasi dengan kredensial pengguna atau dengan delegasi seluruh domain menggunakan cakupan ini. |
https://www.googleapis.com/auth/chat.app.spaces.create
|
Membuat percakapan dan ruang baru di Chat. Memerlukan persetujuan administrator. Cakupan ini hanya mendukung autentikasi aplikasi dengan akun layanan. Anda tidak dapat mengotentikasi dengan kredensial pengguna atau dengan delegasi tingkat domain menggunakan cakupan ini. |
https://www.googleapis.com/auth/chat.app.memberships
|
Melihat, menambahkan, memperbarui, dan menghapus anggota dari percakapan dan ruang di Chat. Memerlukan persetujuan administrator. Cakupan ini hanya mendukung autentikasi aplikasi dengan akun layanan. Anda tidak dapat melakukan autentikasi dengan kredensial pengguna atau dengan delegasi seluruh domain menggunakan cakupan ini. |
https://www.googleapis.com/auth/chat.customemojis
|
Melihat, membuat, dan menghapus emoji kustom di Chat. |
Cakupan yang dibatasi
| Kode cakupan | Deskripsi |
|---|---|
https://www.googleapis.com/auth/chat.delete
|
Menghapus percakapan dan ruang, serta menghapus akses ke file terkait di Chat. |
https://www.googleapis.com/auth/chat.import
|
Mengimpor ruang, pesan, dan keanggotaan ke Chat. Sebagai informasi selengkapnya, lihat Mengizinkan aplikasi Chat untuk mengimpor data |
https://www.googleapis.com/auth/chat.messages
|
Melihat, menulis, mengirim, memperbarui, dan menghapus pesan, serta menambahkan, melihat, dan menghapus reaksi terhadap pesan. |
https://www.googleapis.com/auth/chat.messages.readonly
|
Melihat pesan dan reaksi di Chat. |
https://www.googleapis.com/auth/chat.admin.delete
|
Menghapus percakapan dan ruang yang dimiliki oleh domain administrator, serta menghapus akses ke file terkait di Chat. |
https://www.googleapis.com/auth/chat.app.delete
|
Menghapus percakapan dan ruang serta menghapus akses ke file terkait di Chat. Memerlukan persetujuan administrator. Cakupan ini hanya mendukung autentikasi aplikasi dengan akun layanan. Anda tidak dapat mengotentikasi dengan kredensial pengguna atau dengan delegasi tingkat domain menggunakan cakupan ini. |
Cakupan dalam tabel sebelumnya menunjukkan sensitivitasnya, sesuai dengan definisi berikut:
Tidak sensitif—Cakupan ini menyediakan cakupan terkecil akses otorisasi dan hanya memerlukan verifikasi aplikasi dasar. Sebagai informasi tentang persyaratan ini, lihat Langkah-langkah yang harus dipersiapkan untuk verifikasi.
Sensitif—Cakupan ini memberi aplikasi Anda akses ke data Google pengguna tertentu setelah menerima otorisasi dari pengguna. Anda harus melakukan verifikasi aplikasi tambahan. Untuk mengetahui informasi tentang persyaratan, lihat Langkah-langkah untuk aplikasi yang meminta informasi cakupan kami.
Dibatasi—Cakupan ini memberikan akses luas ke data pengguna Google dan mengharuskan Anda melalui proses verifikasi cakupan yang dibatasi. Untuk mengetahui informasi tentang persyaratan ini, lihat Layanan Google API: Kebijakan Data Pengguna dan Persyaratan Tambahan untuk Cakupan API Tertentu. Lihat juga Langkah-langkah untuk aplikasi yang meminta cakupan yang dibatasi.
Jika aplikasi Anda memerlukan akses ke API Google lainnya, Anda juga dapat menambahkan cakupan tersebut. Untuk informasi selengkapnya tentang cakupan Google API, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.
Untuk mempelajari lebih lanjut cakupan untuk Google Workspace API, lihat Konfigurasi layar izin OAuth dan pilih cakupan.
Jenis autentikasi yang diperlukan
Ada dua cara aplikasi Chat dapat melakukan autentikasi dan otorisasi dengan Chat API:
- Autentikasi pengguna
- Autentikasi pengguna memungkinkan aplikasi Chat mengakses data pengguna dan menyelesaikan tindakan atas nama pengguna. Cakupan OAuth menentukan data dan tindakan yang diizinkan. Kecuali jika aplikasi Chat diinstal oleh admin atau diberikan delegasi tingkat domain, saat pertama kali aplikasi Chat melakukan tindakan pada atas nama pengguna, pengguna harus mengizinkan aplikasi Chat menggunakan layar izin OAuth.
- Autentikasi aplikasi
Autentikasi aplikasi memungkinkan Aplikasi Chat menggunakan kredensial dan akses akun layanan data dan menyelesaikan tindakan seperti dirinya sendiri. Karena aplikasi Chat menggunakan kredensialnya sendiri untuk mengakses dan bekerja dengan sumber daya, pengguna akhir tidak perlu menyetujui Panggilan API aplikasi Chat, dan Anda tidak dapat menambahkan cakupan otorisasi OAuth yang mendukung otorisasi aplikasi ke layar izin OAuth.
Dua jenis cakupan otorisasi OAuth mendukung autentikasi aplikasi:
https://www.googleapis.com/auth/chat.bot: Aplikasi Chat Anda dapat memanggil Google Chat API yang mendukung cakupan otorisasi ini untuk membuat, memperbarui, mendapatkan, mencantumkan, atau menghapus resource yang dapat diakses, seperti pesan dalam ruang tempat pengguna akhir menambahkan aplikasi Chat Anda. Nama Aplikasi Chat dapat memberikan cakupan otorisasi ini sendiri, tidak diperlukan otorisasi administrator atau pengguna akhir.https://www.googleapis.com/auth/chat.app.*(Pratinjau Developer): Penggunaan cakupan ini memerlukan persetujuan administrator satu kali. Untuk mendapatkan persetujuan administrator, Anda menyiapkan akun layanan aplikasi Chat untuk menerima persetujuan administrator dengan membuat klien OAuth yang kompatibel dengan Google Workspace Marketplace dan mengonfigurasi aplikasi di Google Workspace Marketplace SDK. Cakupan ini mengizinkan aplikasi Chat Anda memanggil Google Chat API tertentu metode. Misalnya,chat.app.spaces.createmengizinkan aplikasi untuk membuat Ruang Chat.
Jika metode mendukung autentikasi pengguna atau aplikasi, Chat API akan menampilkan hasil yang berbeda berdasarkan jenis autentikasi yang Anda gunakan:
- Dengan autentikasi aplikasi, metode hanya akan mengembalikan resource yang Aplikasi Chat dapat mengakses.
- Dengan autentikasi pengguna, metode tersebut hanya menampilkan resource yang pengguna yang dapat diakses.
Misalnya, memanggil metode spaces.list() dengan otorisasi aplikasi akan menampilkan
daftar ruang tempat aplikasi Chat menjadi anggota.
Memanggil spaces.list() dengan
otorisasi pengguna akan menampilkan daftar ruang tempat pengguna menjadi anggota. Dalam prakteknya, Anda dapat menggunakan kedua jenis autentikasi saat memanggil Chat API, bergantung pada desain dan fitur aplikasi Chat Anda.
Untuk panggilan Chat API asinkron
Tabel berikut mencantumkan metode Chat API dan cakupan otorisasi yang didukungnya:
| Metode | Autentikasi pengguna didukung | Autentikasi aplikasi didukung | Cakupan otorisasi yang didukung | |
|---|---|---|---|---|
| Ruang | ||||
| Membuat ruang |
Dengan Autentikasi pengguna:
|
|||
| Menyiapkan ruang | — |
Dengan Autentikasi pengguna:
|
||
| Mendapatkan ruang |
Dengan Autentikasi pengguna:
|
|||
| Menampilkan daftar ruang |
Dengan Autentikasi pengguna:
|
|||
| Ruang penelusuran | — |
Dengan Autentikasi pengguna menggunakan hak istimewa administrator:
|
||
| Memperbarui ruang |
Dengan Autentikasi pengguna:
|
|||
| Menghapus ruang |
Dengan Autentikasi pengguna:
|
|||
| Menyelesaikan proses impor untuk ruang | — |
Dengan Autentikasi pengguna:
|
||
| Menemukan pesan langsung |
Dengan Autentikasi pengguna:
|
|||
| Anggota | ||||
| Membuat anggota |
Dengan Autentikasi pengguna:
|
|||
| Dapatkan pelanggan |
Dengan Autentikasi pengguna:
|
|||
| Mencantumkan anggota |
Dengan Autentikasi pengguna:
|
|||
| Menghapus anggota |
Dengan Autentikasi pengguna:
|
|||
| Memperbarui anggota |
Dengan Autentikasi pengguna:
|
|||
| Pesan | ||||
| Membuat pesan |
Dengan Autentikasi pengguna:
|
|||
| Mendapatkan pesan |
Dengan Autentikasi pengguna:
|
|||
| Daftar pesan | — |
Dengan Autentikasi pengguna:
|
||
| Memperbarui pesan |
Dengan Autentikasi pengguna:
|
|||
| Menghapus pesan |
Dengan Autentikasi pengguna:
|
|||
| Reaksi | ||||
| Membuat reaksi | — |
Dengan Autentikasi pengguna:
|
||
| Daftar reaksi | — |
Dengan Autentikasi pengguna:
|
||
| Menghapus reaksi | — |
Dengan Autentikasi pengguna:
|
||
| Emoji kustom | ||||
| Membuat emoji kustom | — |
Dengan Autentikasi pengguna:
|
||
| Menghapus emoji kustom | — |
Dengan Autentikasi pengguna:
|
||
| Mendapatkan emoji kustom | — |
Dengan Autentikasi pengguna:
|
||
| Mencantumkan emoji kustom | — |
Dengan Autentikasi pengguna:
|
||
| Media & lampiran | ||||
| Mengupload media sebagai lampiran file | — |
Dengan Autentikasi pengguna:
|
||
| Mendownload media |
Dengan Autentikasi pengguna:
|
|||
| Mendapatkan lampiran pesan | — |
Dengan Autentikasi aplikasi:
|
||
| Status pembacaan pengguna | ||||
| Mendapatkan status pembacaan ruang pengguna | — |
Dengan Autentikasi pengguna:
|
||
| Memperbarui status pembacaan ruang pengguna | — |
Dengan Autentikasi pengguna:
|
||
| Mendapatkan status bacaan rangkaian pesan pengguna | — |
Dengan Autentikasi pengguna:
|
||
| Acara ruang | ||||
| Mendapatkan peristiwa ruang | — |
Dengan Autentikasi pengguna,
Anda harus menggunakan
ruang lingkup berdasarkan
jenis peristiwa:
|
||
| Mencantumkan peristiwa ruang | — |
Dengan Autentikasi pengguna,
Anda harus menggunakan cakupan untuk setiap
jenis peristiwa yang disertakan dalam permintaan:
|
||
Untuk peristiwa interaksi aplikasi Chat
Tabel berikut mencantumkan cara umum pengguna berinteraksi dengan aplikasi Chat dan apakah autentikasi diperlukan atau didukung:
| Skenario | Tidak diperlukan autentikasi | Autentikasi pengguna didukung | Autentikasi aplikasi didukung | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Menerima pesan dari: |
|
|||||||||||||||
| Membalas pesan: |
|
|||||||||||||||
| Mengirim pesan baru: |
|
|||||||||||||||
Topik terkait
- Untuk ringkasan tentang autentikasi dan otorisasi di Google Workspace, lihat Mempelajari autentikasi & otorisasi.
- Untuk ringkasan autentikasi dan otorisasi di Google Cloud, lihat Ringkasan autentikasi.
- Untuk mempelajari akun layanan lebih lanjut, lihat Akun layanan.
- Untuk mempelajari lebih lanjut cara Google API menggunakan OAuth 2.0, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.
- Siapkan autentikasi dan otorisasi dengan kredensial pengguna atau akun layanan.