Jenis penautan akun OAuth mendukung dua alur OAuth 2.0 standar industri: alur implisit dan kode otorisasi. Dalam alur kode implisit, Google akan membuka endpoint otorisasi Anda di browser pengguna. Setelah berhasil login, Anda akan menampilkan token akses yang berumur panjang ke Google. Token akses ini kemudian disertakan dalam setiap permintaan yang dikirim dari Asisten ke Action Anda.
OAuth adalah solusi penautan akun yang direkomendasikan jika hal berikut berlaku:
- Anda sudah memiliki implementasi server OAuth 2.0, dan tidak dapat memperluas endpoint pertukaran token guna menambahkan dukungan bagi protokol Google untuk penautan otomatis dan pembuatan akun dari token ID (misalnya, menambahkan parameter
intent=getdanintent=createdalam permintaan ke endpoint ini).
Untuk memverifikasi bahwa OAuth adalah solusi yang tepat bagi Anda, lihat halaman Memilih jenis penautan akun.
Istilah utama
Sebelum membaca cara kerja OAuth, pelajari istilah berikut:
- Intent helper login akun: Intent helper yang Anda panggil untuk meminta
alur penautan akun dari Asisten. Untuk informasi selengkapnya, lihat Login Akun.
- String konteks: String kustom yang Anda tambahkan ke intent helper login akun yang memberi tahu pengguna alasan Anda mengharuskan mereka menautkan akunnya.
Alur kode otorisasi: Selama alur OAuth 2.0 ini, Google akan membuka endpoint otorisasi Anda di browser pengguna. Jika login berhasil, layanan Anda akan membuat kode otorisasi dan mengembalikannya ke Google. Google mengirimkan kode otorisasi ini ke endpoint pertukaran token Anda, yang memverifikasi keaslian kode serta menampilkan token akses dan token refresh.
Alur ini memerlukan dua endpoint:
- Endpoint otorisasi: Endpoint yang bertanggung jawab untuk menemukan atau mendapatkan izin dari pengguna untuk akses data. Endpoint ini melakukan
hal berikut:
- Menampilkan UI login kepada pengguna yang belum login.
- Data mengizinkan akses yang diminta dalam bentuk kode otorisasi berumur singkat.
- Endpoint pertukaran token: Endpoint ini digunakan untuk mendapatkan string terenkripsi
yang disebut token, yang mengizinkan pengguna Action untuk mengakses
layanan Anda. Endpoint ini bertanggung jawab atas dua jenis pertukaran:
- Menukar kode otorisasi dengan token refresh yang memiliki masa aktif lama dan token akses yang memiliki masa aktif singkat. Pertukaran ini terjadi saat pengguna melalui alur penautan akun.
- Menukar token refresh yang berumur panjang dengan token akses yang berumur singkat. Pertukaran ini terjadi saat Google memerlukan token akses baru karena token yang sudah habis masa berlakunya.
- Endpoint otorisasi: Endpoint yang bertanggung jawab untuk menemukan atau mendapatkan izin dari pengguna untuk akses data. Endpoint ini melakukan
hal berikut:
Alur kode implisit: Selama alur OAuth 2.0 ini, Google akan membuka endpoint otorisasi Anda di browser pengguna. Jika login berhasil, Anda akan menampilkan token akses berumur panjang ke Google. Token akses ini kemudian disertakan dalam setiap permintaan yang dikirim dari Asisten ke Action Anda. Alur ini hanya memerlukan endpoint otorisasi.
Token akses: Token yang memberikan otorisasi kepada layanan Anda untuk mengakses bagian-bagian data pengguna. Token akses dikaitkan dengan setiap pengguna individu dan harus tidak dapat diprediksi.
Token refresh: Token yang ditukarkan dengan token akses baru setelah masa berlaku token akses singkat berakhir.
Cara kerjanya
Bagian ini menjelaskan alur umum untuk kode otorisasi OAuth dan alur implisit. Bagian berikut, Alur OAuth, menjelaskan berbagai alur yang dapat terjadi dengan OAuth.
Alur kode otorisasi dapat diringkas sebagai berikut:
- Action Anda akan menanyakan apakah pengguna ingin menautkan akunnya dengan layanan Anda.
- Setelah pengguna setuju untuk menautkan akun, Google akan membuka endpoint otorisasi Anda di browser pengguna. Jika alur dimulai di perangkat suara-saja untuk Action, Google akan mentransfer eksekusi ke ponsel.
- Pengguna akan login (jika belum login) dan memberikan izin kepada Google untuk mengakses data mereka dengan API Anda (jika mereka belum memberikan izin).
- Layanan Anda membuat kode otorisasi, lalu mengembalikannya ke Google dengan mengalihkan browser pengguna kembali ke Google dengan kode otorisasi yang disertakan pada permintaan.
- Google mengirimkan kode otorisasi ke endpoint pertukaran token Anda, yang memverifikasi keaslian kode dan menampilkan token akses serta token refresh. Token akses adalah token berumur singkat yang diterima layanan Anda sebagai kredensial untuk mengakses API. Token refresh adalah token berumur panjang yang dapat disimpan dan digunakan Google untuk memperoleh token akses baru saat masa berlakunya habis.
- Setelah pengguna menyelesaikan alur penautan akun, setiap permintaan berikutnya yang dikirim dari Asisten ke webhook fulfillment Anda akan berisi token akses.
Alur kode implisit dapat diringkas sebagai berikut:
- Action Anda akan menanyakan kepada pengguna apakah mereka ingin menautkan akunnya dengan layanan Anda.
- Setelah pengguna setuju untuk menautkan akun, Google akan membuka endpoint otorisasi Anda di browser pengguna.
- Pengguna akan login (jika belum login) dan memberikan izin kepada Google untuk mengakses data mereka dengan API Anda (jika mereka belum memberikan izin).
- Layanan Anda membuat token akses dan menampilkannya ke Google dengan mengalihkan browser pengguna kembali ke Google dengan token akses yang dilampirkan ke permintaan.
- Setelah pengguna menyelesaikan alur penautan akun, Google akan memanggil API layanan Anda dan melampirkan token akses bersama setiap permintaan. Layanan Anda memverifikasi bahwa token akses memberikan otorisasi kepada Google untuk mengakses API, lalu menyelesaikan panggilan API.
Alur kode otorisasi dasar adalah sebagai berikut:
- Action Anda akan menanyakan apakah pengguna ingin menautkan akunnya dengan layanan Anda.
- Setelah pengguna setuju untuk menautkan akun, Google akan membuka endpoint otorisasi Anda di browser pengguna. Jika alur dimulai di perangkat suara-saja untuk Action, Google akan mentransfer eksekusi ke ponsel.
- Pengguna akan login (jika belum login) dan memberikan izin kepada Google untuk mengakses data mereka dengan API Anda (jika mereka belum memberikan izin).
- Layanan Anda membuat kode otorisasi dan mengembalikannya ke Google dengan mengalihkan browser pengguna kembali ke Google dengan kode otorisasi berumur singkat yang dilampirkan pada permintaan.
- Google mengirimkan kode otorisasi ke endpoint pertukaran token Anda, yang memverifikasi keaslian kode dan menampilkan token akses serta token refresh. Token akses adalah token berumur singkat yang diterima layanan Anda sebagai kredensial untuk mengakses API. Token refresh adalah token berumur panjang yang dapat disimpan dan digunakan Google untuk memperoleh token akses baru saat masa berlakunya habis.
- Setelah pengguna menyelesaikan alur penautan akun, setiap permintaan berikutnya yang dikirim dari Asisten ke webhook fulfillment Anda akan berisi token akses.
Alur OAuth
Bagian ini membahas berbagai alur yang dapat terjadi dengan OAuth.
Setiap alur berisi langkah-langkah umum ini setelah pengguna memanggil Action Anda:
Pada alur di atas, Anda memanggil intent helper actions.intent.SIGN_IN untuk memulai
alur penautan akun. Asisten akan bertanya kepada pengguna apakah mereka ingin
menautkan akunnya dengan layanan Anda dan menampilkan layar dengan izin
yang diminta. Jika pengguna mengizinkan, Google akan mengalihkan pengguna ke endpoint otorisasi layanan Anda di browser. Pengguna login (atau,
bergantung pada konfigurasi Anda, membuat akun baru) dan memberi Action Anda
izin untuk mengakses datanya.
Alur setelah titik ini berbeda berdasarkan apakah Anda menerapkan alur implisit atau alur kode otorisasi. Alur ini dijelaskan di bagian berikut.
Alur 1: Pengguna login dengan alur implisit
Setelah pengguna login dan kredensialnya diverifikasi, layanan Anda akan membuat token akses yang berumur panjang dan mengembalikannya ke Google. Pada tahap ini, identitas pengguna di Action Anda akan ditautkan ke akun yang digunakan untuk login, dan token akses dilampirkan ke setiap panggilan API yang dilakukan Google ke API layanan Anda.
Alur 2: Pengguna login dengan alur kode otorisasi
Setelah pengguna login dan kredensialnya diverifikasi, layanan Anda akan membuat kode otorisasi dan menampilkannya ke Google.
Kode otorisasi ini dikirim ke endpoint pertukaran token Anda, yang menampilkan token akses dan token refresh. Pada tahap ini, identitas pengguna di Action Anda ditautkan ke akun apa pun yang mereka gunakan untuk login, dan setiap permintaan berikutnya yang dikirim dari Asisten ke fulfillment Anda berisi token akses.