Autentikasi dan otorisasi adalah mekanisme yang digunakan untuk memverifikasi identitas dan akses ke resource. Dokumen ini menguraikan cara kerja autentikasi dan otorisasi untuk aplikasi Chat dan permintaan Chat API.
Ringkasan proses
Diagram berikut menunjukkan langkah-langkah tingkat tinggi autentikasi dan otorisasi untuk Google Chat:
Mengonfigurasi project Google Cloud, mengaktifkan Chat API, dan mengonfigurasi aplikasi Chat: Selama pengembangan, Anda akan membuat project Google Cloud. Di project Google Cloud, Anda dapat mengaktifkan Chat API, mengonfigurasi aplikasi Chat, dan menyiapkan autentikasi. Untuk mengetahui informasi selengkapnya, lihat Mengembangkan di Google Workspace dan Mem-build aplikasi Chat.
Call Chat API: Saat memanggil Chat API, aplikasi akan mengirimkan kredensial autentikasi ke Chat API. Jika aplikasi Anda melakukan autentikasi dengan akun layanan, kredensial akan dikirim sebagai bagian dari kode aplikasi Anda. Jika aplikasi Anda memerlukan pemanggilan Chat API menggunakan autentikasi pengguna yang belum diberikan, aplikasi akan meminta pengguna untuk login.
Minta resource: Aplikasi Anda meminta akses dengan cakupan yang Anda tentukan saat menyiapkan autentikasi.
Minta izin: Jika aplikasi Anda melakukan autentikasi sebagai pengguna, Google akan menampilkan layar izin OAuth sehingga pengguna dapat memutuskan apakah akan memberi aplikasi Anda akses ke data yang diminta. Autentikasi dengan akun layanan tidak memerlukan izin pengguna.
Kirim permintaan resource yang disetujui: Jika pengguna mengizinkan cakupan otorisasi, aplikasi Anda akan memaketkan kredensial dan cakupan yang disetujui pengguna menjadi 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 ketat 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 habis, aplikasi tersebut bisa mendapatkan token refresh. Untuk informasi selengkapnya, lihat Menggunakan OAuth 2.0 untuk mengakses Google API.
Minta lebih banyak resource: Jika aplikasi Anda memerlukan lebih banyak akses, aplikasi akan meminta pengguna untuk memberikan cakupan baru, yang 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 di ruang Chat.
Aplikasi Chat tidak memerlukan autentikasi untuk merespons interaksi pengguna, kecuali jika aplikasi Chat memanggil Chat API atau Google API lain saat memproses respons.
Untuk mengirim pesan asinkron atau melakukan tugas atas nama pengguna, aplikasi Chat membuat permintaan RESTful ke Chat API, yang memerlukan autentikasi dan otorisasi.
Respons terhadap interaksi pengguna tidak memerlukan otentikasi
Aplikasi Google Chat tidak perlu mengautentikasi sebagai pengguna atau aplikasi Chat untuk menerima dan merespons peristiwa interaksi secara sinkron.
Aplikasi Google Chat menerima peristiwa interaksi setiap kali pengguna berinteraksi atau memanggil aplikasi Chat, termasuk hal berikut:
- Pengguna mengirim pesan ke aplikasi Chat.
- Pengguna memberi @sebutan untuk aplikasi Chat.
- Pengguna memanggil salah satu perintah garis miring aplikasi Chat.
Diagram berikut menunjukkan urutan permintaan-respons antara pengguna Chat dan aplikasi Chat:
- Pengguna mengirim pesan ke aplikasi Chat di Google Chat.
- Google Chat meneruskan pesan ke aplikasi.
- Aplikasi menerima pesan, memprosesnya, dan menampilkan respons ke Google Chat.
- Google Chat merender respons untuk pengguna, atau dalam ruang.
Urutan ini berulang 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 penonaktifan server, aplikasi Chat dapat memanggil Chat API untuk:
- Buat ruang Chat khusus untuk menyelidiki dan memperbaiki pemadaman.
- Menambahkan orang ke ruang Chat.
- Posting pesan ke ruang Chat untuk memberikan detail pemadamannya.
Diagram berikut menunjukkan urutan pesan asinkron antara aplikasi Chat dan ruang Chat:
- Aplikasi Chat membuat pesan dengan memanggil Chat API menggunakan metode
spaces.messages.create, dan menyertakan kredensial pengguna dalam permintaan HTTP. - Google Chat mengautentikasi aplikasi Chat dengan akun layanan atau kredensial pengguna.
- Google Chat merender pesan aplikasi ke ruang Chat yang ditentukan.
Cakupan Chat API
Konfigurasi layar izin OAuth aplikasi Anda dan pilih cakupan untuk menentukan informasi yang ditampilkan kepada pengguna dan peninjau aplikasi, serta mendaftarkan aplikasi agar dapat dipublikasikan nanti.
Untuk menentukan tingkat akses yang diberikan ke aplikasi, Anda perlu mengidentifikasi dan mendeklarasikan cakupan otorisasi. Cakupan otorisasi adalah string URI OAuth 2.0 yang berisi nama aplikasi Google Workspace, jenis data yang diakses, dan tingkat akses.
Cakupan tidak sensitif
| Kode cakupan | Deskripsi |
|---|---|
https://www.googleapis.com/auth/chat.bot
|
Mengizinkan aplikasi Chat melihat chat dan mengirim pesan. Memberikan akses ke semua fitur yang tersedia untuk aplikasi Chat. |
Cakupan sensitif
| Kode cakupan | Deskripsi |
|---|---|
https://www.googleapis.com/auth/chat.spaces
|
Membuat percakapan dan ruang serta melihat atau memperbarui metadata (termasuk setelan histori) 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, dan menghapus anggota dari percakapan di Chat. |
https://www.googleapis.com/auth/chat.memberships.app
|
Menambahkan dan menghapus diri sendiri dari percakapan di Google Chat. |
https://www.googleapis.com/auth/chat.memberships.readonly
|
Melihat anggota di 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 terhadap pesan di Chat. |
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
Melihat reaksi terhadap pesan 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.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. |
Cakupan dalam tabel sebelumnya menunjukkan sensitivitasnya, sesuai dengan definisi berikut:
Tidak sensitif—Cakupan ini memberikan cakupan akses otorisasi terkecil dan hanya memerlukan verifikasi aplikasi dasar. Untuk mengetahui informasi tentang persyaratan ini, lihat Langkah-langkah untuk menyiapkan verifikasi.
Sensitif—Cakupan ini memberi aplikasi Anda akses ke data Google pengguna tertentu setelah menerima otorisasi dari pengguna. Anda harus melalui verifikasi aplikasi tambahan. Untuk mengetahui informasi tentang persyaratan ini, lihat Langkah-langkah untuk aplikasi yang meminta cakupan sensitif.
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 memerlukan akses ke Google API lain, Anda juga dapat menambahkan cakupan tersebut. Untuk informasi selengkapnya tentang cakupan Google API, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.
Untuk mempelajari cakupan untuk Google Workspace API lebih lanjut, lihat Mengonfigurasi layar izin OAuth dan memilih cakupan.
Jenis autentikasi yang diperlukan
Ada dua cara yang dapat digunakan aplikasi Chat untuk mengautentikasi dan memberikan otorisasi dengan Chat API: kredensial pengguna atau akun layanan.
Dengan otorisasi kredensial pengguna, aplikasi Chat dapat mengakses data pengguna dan menyelesaikan tindakan atas nama pengguna. Cakupan OAuth menentukan data dan tindakan yang diotorisasi. Namun, aplikasi Chat ini tidak dapat dipublikasikan secara publik. Untuk informasi selengkapnya, lihat Memublikasikan aplikasi Google Chat.
Dengan otorisasi aplikasi, aplikasi Chat mengakses
API sebagai aplikasi menggunakan kredensial akun layanan. Otorisasi aplikasi selalu
menggunakan cakupan otorisasi chat.bot.
Jika Anda merupakan administrator domain, Anda dapat memberikan delegasi otoritas tingkat domain untuk mengizinkan akun layanan aplikasi mengakses data pengguna Anda tanpa mengharuskan setiap pengguna memberikan izin. Setelah mengonfigurasi delegasi di seluruh domain, Anda dapat melakukan panggilan API menggunakan akun layanan untuk meniru identitas akun pengguna. Meskipun akun layanan digunakan untuk autentikasi, delegasi seluruh domain meniru identitas pengguna sehingga dianggap sebagai autentikasi pengguna. Setiap fungsi yang memerlukan autentikasi pengguna, dapat menggunakan delegasi di seluruh domain.
Saat menentukan jenis kredensial yang akan digunakan untuk permintaan API tertentu, perlu diingat bahwa beberapa metode API hanya mendukung jenis kredensial tertentu. Jika metode API mendukung kedua kredensial, jenis kredensial yang digunakan dalam panggilan akan memengaruhi hasil yang ditampilkan:
- Dengan otorisasi aplikasi, metode hanya menampilkan resource yang dapat diakses aplikasi.
- Dengan otorisasi pengguna, metode hanya menampilkan resource yang dapat diakses oleh pengguna di UI Chat.
Misalnya, memanggil metode ListSpaces dengan otorisasi aplikasi akan menampilkan
daftar ruang tempat aplikasi menjadi anggota. Memanggil ListSpaces dengan otorisasi pengguna akan menampilkan daftar ruang tempat pengguna menjadi anggota. Dalam
praktiknya, aplikasi Anda mungkin menggunakan kedua jenis otorisasi saat memanggil
Chat API, bergantung pada fungsi yang Anda inginkan.
Untuk panggilan Chat API asinkron
Tabel berikut mencantumkan metode Chat API dan cakupan otorisasinya yang didukung:
| Metode | Autentikasi pengguna didukung | Autentikasi aplikasi didukung | Cakupan otorisasi yang didukung | |
|---|---|---|---|---|
| Ruang | ||||
| Membuat ruang | — |
|
||
| Menyiapkan ruang | — |
|
||
| Dapatkan ruang |
Dengan Autentikasi pengguna:
|
|||
| Mencantumkan ruang |
Dengan Autentikasi pengguna:
|
|||
| Memperbarui ruang | — |
|
||
| Menghapus ruang | — |
|
||
| Menemukan pesan langsung |
Dengan Autentikasi pengguna:
|
|||
| Anggota | ||||
| Membuat anggota | — |
|
||
| Mendapatkan pelanggan |
Dengan Autentikasi pengguna:
|
|||
| Anggota daftar |
Dengan Autentikasi pengguna:
|
|||
| Menghapus anggota | — |
|
||
| Pesan | ||||
| Membuat pesan |
Dengan Autentikasi pengguna:
|
|||
| Menerima pesan |
Dengan Autentikasi pengguna:
|
|||
| Mencantumkan pesan | — |
|
||
| Memperbarui pesan |
Dengan Autentikasi pengguna:
|
|||
| Menghapus pesan |
Dengan Autentikasi pengguna:
|
|||
| Reaksi | ||||
| Membuat reaksi | — |
|
||
| Menampilkan daftar reaksi | — |
|
||
| Menghapus reaksi | — |
|
||
| Media & lampiran | ||||
| Mengupload media sebagai lampiran file | — |
|
||
| Download media |
Dengan Autentikasi pengguna:
|
|||
| Mendapatkan lampiran pesan | — |
|
||
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 | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Terima pesan dari: |
|
|||||||||||||||
| Membalas pesan: |
|
|||||||||||||||
| Mengirim pesan baru: |
|
|||||||||||||||
Topik terkait
- Untuk ringkasan tentang autentikasi dan otorisasi di Google Workspace, lihat Mempelajari autentikasi & otorisasi.
- Untuk ringkasan tentang 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 memanfaatkan OAuth 2.0, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.
- Siapkan autentikasi dan otorisasi dengan kredensial pengguna atau akun layanan.