Panduan konsep penautan OAuth

Jenis penautan 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.

Penautan 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=get dan intent=create dalam permintaan ke endpoint ini).

Untuk memastikan bahwa penautan OAuth adalah solusi yang tepat bagi Anda, lihat halaman Memilih jenis penautan akun.

Istilah utama

Sebelum membaca cara kerja penautan OAuth, pelajari istilah berikut:

• user.verificationStatus: Properti yang ditetapkan oleh sistem untuk menunjukkan apakah sesi saat ini memiliki pengguna terverifikasi.

• user.accountLinkingStatus: Properti yang ditetapkan oleh sistem untuk menunjukkan apakah pengguna dalam sesi saat ini memiliki identitas tertaut.

• Scene sistem penautan akun: Scene yang telah ditetapkan yang menerapkan alur konfirmasi untuk penautan akun, dan dapat disesuaikan agar sesuai dengan kasus penggunaan tertentu.

• 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:
    1. Menampilkan UI login kepada pengguna yang belum login.
    2. 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:
    1. 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.
    2. 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.

• 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 penautan OAuth, menjelaskan berbagai alur yang dapat terjadi dengan OAuth.

Alur kode otorisasi dapat diringkas sebagai berikut:

1. Action Anda akan menanyakan apakah pengguna ingin menautkan akunnya dengan layanan Anda.
2. 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.
3. Pengguna akan login (jika belum login) dan memberikan izin kepada Google untuk mengakses data mereka dengan API Anda (jika mereka belum memberikan izin).
4. Layanan Anda membuat kode otorisasi, lalu mengembalikannya ke Google dengan mengalihkan browser pengguna kembali ke Google dengan kode otorisasi yang disertakan pada permintaan.
5. 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.
6. 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:

1. Action Anda akan menanyakan kepada pengguna apakah mereka ingin menautkan akunnya dengan layanan Anda.
2. Setelah pengguna setuju untuk menautkan akun, Google akan membuka endpoint otorisasi Anda di browser pengguna.
3. Pengguna akan login (jika belum login) dan memberikan izin kepada Google untuk mengakses data mereka dengan API Anda (jika mereka belum memberikan izin).
4. Layanan Anda membuat token akses dan menampilkannya ke Google dengan mengalihkan browser pengguna kembali ke Google dengan token akses yang dilampirkan ke permintaan.
5. 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:

1. Action Anda akan menanyakan apakah pengguna ingin menautkan akunnya dengan layanan Anda.
2. 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.
3. Pengguna akan login (jika belum login) dan memberikan izin kepada Google untuk mengakses data mereka dengan API Anda (jika mereka belum memberikan izin).
4. 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.
5. 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.
6. Setelah pengguna menyelesaikan alur penautan akun, setiap permintaan berikutnya yang dikirim dari Asisten ke webhook fulfillment Anda akan berisi token akses.

Alur penautan OAuth

Bagian ini membahas berbagai alur yang dapat terjadi dengan penautan OAuth.

Catatan: Alur berikut mengasumsikan bahwa pengguna setuju untuk menautkan akunnya dengan layanan Anda dan memberi Google izin untuk mengakses datanya dengan API Anda. Jika pengguna tidak memberikan izin, beri mereka cara untuk melanjutkan Action Anda dengan alur alternatif yang terbatas. Untuk mengetahui informasi selengkapnya, lihat Praktik terbaik.

Setiap alur berisi langkah-langkah umum ini setelah pengguna memanggil Action Anda:

Catatan: Baris dari Webhook ke User mewakili respons sederhana yang Anda buat dan sesuaikan. Garis yang digambar dari Asisten ke Pengguna mewakili perintah yang dimiliki oleh Asisten dan memiliki opsi terbatas untuk penyesuaian (permintaan yang memerlukan izin selalu dimiliki oleh Asisten). Dari perspektif pengguna, kedua jenis respons dikirimkan dari Asisten.

Pada alur di atas, Anda beralih ke scene sistem penautan akun dan memberikan alasan yang disesuaikan. Asisten akan meminta pengguna untuk 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

Catatan: Diagram ini dibuat dari diagram Langkah umum di atas.

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

Catatan: Diagram ini dibuat dari diagram Langkah umum di atas.

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.