Panduan konsep penautan Login dengan Google berbasis OAuth yang "Sederhana"

Jenis penautan "Disederhanakan" Login dengan Google berbasis OAuth menambahkan Login dengan Google di atas penautan akun berbasis OAuth. Jika Anda menggunakan jenis penautan ini di Action, alurnya akan dimulai dengan Login dengan Google, yang memungkinkan Anda memeriksa apakah informasi profil Google pengguna ada di sistem Anda. Jika tidak, alur OAuth standar akan dimulai. Dengan memberikan kombinasi dari kedua jenis penautan ini, pengguna Anda dapat menautkan identitas mereka di Action dengan Akun Google atau non-Google. Jika mau, mereka juga dapat membuat akun baru dengan informasi profil Google mereka.

Penautan yang disederhanakan adalah solusi penautan akun yang direkomendasikan jika salah satu dari hal berikut berlaku:

• Anda memiliki Action yang mencakup beberapa platform (misalnya, jika Action berfungsi dengan aplikasi Android).
• Anda sudah memiliki sistem autentikasi dan ingin mengizinkan pengguna untuk menautkan identitas mereka dengan akun non-Google. Misalnya, jika Anda menawarkan program loyalitas dan ingin memastikan bahwa pengguna tidak kehilangan poin yang diperoleh di akun mereka yang sudah ada.

Untuk memverifikasi bahwa Penautan yang disederhanakan adalah solusi yang tepat bagi Anda, lihat halaman Memilih jenis penautan akun.

Istilah utama

Sebelum membaca cara kerja Penautan sederhana, pahami persyaratan berikut:

• Token ID Google: Pernyataan bertanda tangan tentang identitas pengguna yang berisi informasi profil Google dasar pengguna (nama, alamat email, dan foto profil mereka). Token ID Google adalah Token Web JSON (JWT). Berikut adalah contoh token yang didekode:

{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

• 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: Alur OAuth 2.0 yang dapat Anda terapkan dengan Penautan yang disederhanakan. Alur ini memerlukan dua endpoint:

  • Endpoint otorisasi: Endpoint yang menyajikan UI login kepada pengguna yang belum login. Otorisasi mencatat izin atas akses yang diminta dalam bentuk kode otorisasi yang memiliki masa aktif singkat.
  • Endpoint pertukaran token: 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: Alur OAuth 2.0 yang dapat Anda terapkan dengan Penautan yang disederhanakan. Alur ini hanya memerlukan endpoint otorisasi. Selama alur ini, Google akan membuka endpoint otorisasi Anda di browser pengguna. Jika login berhasil, Anda akan menampilkan token akses yang berumur panjang ke Google. Token akses ini kini disertakan dalam setiap permintaan yang dikirim dari Asisten ke Action Anda.

• Token akses: Token yang memberikan otorisasi kepada layanan Anda untuk mengakses bagian-bagian data pengguna. Token akses dikaitkan dengan setiap pengguna individu.

• Token refresh: Token yang ditukarkan dengan token akses baru setelah masa berlaku token akses singkat berakhir.

Prasyarat

Untuk menggunakan jenis penautan Sederhana, Anda memerlukan hal berikut:

• Server OAuth 2.0

• Endpoint pertukaran token

  Endpoint pertukaran token harus diperluas guna menambahkan dukungan bagi protokol Google untuk penautan otomatis dan pembuatan akun dari token ID (yaitu, menambahkan parameter intent=get dan intent=create dalam permintaan ke endpoint ini).

Cara kerjanya

Bagian ini menjelaskan alur umum untuk Penautan yang disederhanakan. Bagian berikut, Alur penautan yang disederhanakan, menjelaskan berbagai alur yang dapat terjadi berdasarkan a) apakah Anda mengaktifkan atau menonaktifkan pembuatan akun melalui suara, dan b) apakah Anda menggunakan alur kode implisit atau otorisasi.

Alur dasarnya adalah sebagai berikut:

1. Action Anda meminta izin kepada pengguna untuk mengakses profil Google-nya.
2. Setelah pengguna memberikan izin, Action Anda akan menerima token ID Google yang berisi informasi profil Google pengguna.
3. Anda harus memvalidasi dan mendekode token untuk membaca konten profil.
4. Action Anda menggunakan token ini untuk memeriksa apakah informasi profil Google pengguna ada di sistem Anda.
   1. Jika ya, berarti pengguna sudah login ke sistem Anda dengan Akun Google mereka, dan Asisten akan menautkan identitas pengguna dengan Akun Google mereka. Pengguna dapat melanjutkan percakapan dengan Asisten dengan akunnya yang ditautkan.
   2. Jika tidak, lihat langkah 5.
5. Pengguna dapat a) membuat akun baru dengan informasi profil Google atau b) login ke sistem Anda dengan akun lain. Pilihan yang ditampilkan kepada pengguna berbeda-beda bergantung pada apakah Anda mengaktifkan atau menonaktifkan pembuatan akun melalui suara. Jika pengguna memilih untuk login ke sistem Anda dengan akun lain, alur OAuth standar dimulai.
6. Setelah pengguna membuat akun baru atau login dengan penyedia yang berbeda, layanan Anda akan menampilkan token akses ke Google. (Jika Anda menggunakan alur kode otorisasi, layanan Anda juga akan menampilkan token refresh.)
7. Pengguna sekarang dapat melanjutkan percakapan dengan Asisten dengan akunnya ditautkan.

Alur penautan yang disederhanakan

Bagian ini membahas berbagai alur yang dapat terjadi dengan Penautan yang disederhanakan. Diagram ini membahas alur yang terjadi dengan alur kode otorisasi, bukan alur kode implisit, dan mengasumsikan bahwa Anda menggunakan Action Builder.

Catatan: Alur berikut mengasumsikan bahwa pengguna memberikan izin agar Action Anda dapat mengakses informasi profil Google mereka. 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:

Pada alur di atas, Anda beralih ke scene sistem penautan akun dan memberikan alasan yang disesuaikan. Scene akan meminta izin kepada pengguna untuk mengakses informasi profil Google mereka. Setelah pengguna mengizinkan, Asisten akan mengirimkan permintaan yang berisi informasi profil untuk [e-mail].

Alur setelah tahap ini berbeda berdasarkan apakah Anda mengonfigurasi penautan akun dengan suara atau tidak, dan apakah informasi pengguna sudah ada di sistem Anda. Setiap alur ini dijelaskan di bagian berikut.

Alur dengan pembuatan akun suara diaktifkan

Bagian ini menjelaskan alur penautan akun yang dapat terjadi jika Anda mengaktifkan pembuatan akun melalui suara.

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

Alur 1: Informasi pengguna ada di sistem Anda

Catatan: Baris dari Webhook ke Pengguna 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 sudut pandang pengguna, kedua jenis respons tersebut dikirimkan dari Asisten.

Dalam hal ini, pengguna yang diwakili oleh [e-mail] ada di backend Anda, sehingga endpoint pertukaran token Anda menampilkan token untuk pengguna tersebut. Identitas pengguna di Action Anda kini ditautkan ke Akun Google mereka. Permintaan asli pengguna (“Pesan seperti yang biasa”) cocok dengan intent pengguna order_drink. Webhook Anda kemudian akan menangani fulfillment intent yang cocok dan mengkueri database untuk pesanan [e-mail] yang biasa. Kemudian, pengguna dapat melanjutkan percakapan dengan Asisten.

Alur 2: Informasi pengguna tidak ada dan pengguna membuat akun

Karena Anda mengaktifkan pembuatan akun melalui suara dan [e-mail] tidak ada di backend, Asisten akan bertanya kepada pengguna apakah mereka ingin melakukan salah satu hal berikut:

a) Membuat akun baru di sistem Anda menggunakan informasi profil Google mereka, yang dapat dilakukan melalui suara

b) Login ke sistem Anda dengan akun yang berbeda

Catatan: Anda juga dapat mengizinkan pengguna membuat akun baru dengan penyedia yang berbeda. Penyedia tersebut adalah penyedia layanan yang Anda sediakan di halaman otorisasi.

Dalam hal ini, pengguna memilih untuk membuat akun baru melalui suara. Google memanggil endpoint pertukaran token layanan Anda dengan permintaan untuk membuat akun. Permintaan ini berisi token ID Google, yang mencakup komponen yang diperlukan untuk membuat akun baru. Selanjutnya, Anda dapat menggunakan informasi dari token ini (nama dan alamat email pengguna) untuk membuat akun bagi pengguna tersebut.

Setelah akun dibuat, layanan Anda akan menampilkan token akses dan token refresh untuk akun yang baru dibuat. Identitas pengguna di Action Anda sekarang ditautkan ke Akun Google mereka. Permintaan asli pengguna (“Pesan seperti biasa”) cocok dengan intent pengguna order_drink. Webhook Anda kemudian akan menangani fulfillment intent yang cocok dan membuat kueri database untuk urutan [e-mail] yang biasa, yang belum ada karena pengguna baru. Action Anda kemudian dapat bertanya kepada pengguna apa yang ingin mereka pesan.

Catatan: Akun baru biasanya tidak memiliki sandi yang ditetapkan. Sebaiknya tambahkan Login dengan Google ke platform lain untuk memungkinkan pengguna login melalui Google di seluruh platform aplikasi Anda. Atau, Anda dapat mengirimkan link melalui email kepada pengguna yang memulai alur pemulihan sandi agar pengguna dapat menetapkan sandi untuk login di platform lain.

Alur 3: Informasi pengguna tidak ada dan pengguna login dengan akun lain

Anda mengaktifkan pembuatan akun melalui suara, sehingga Asisten akan bertanya kepada pengguna apakah mereka ingin melakukan salah satu hal berikut:

a) Membuat akun baru di sistem Anda menggunakan informasi profil Google mereka, yang dapat dilakukan melalui suara

b) Login ke sistem Anda dengan akun yang berbeda

Catatan: Anda juga dapat mengizinkan pengguna membuat akun baru dengan penyedia lain. Penyedia tersebut adalah penyedia yang Anda sediakan di halaman otorisasi Anda.

Dalam hal ini, pengguna memilih untuk login dengan akun lain, yang memulai alur OAuth standar. Jika alur dimulai di perangkat suara saja, Google akan mentransfer eksekusi ke ponsel. Kemudian, Google akan membuka endpoint otorisasi Anda di browser pengguna. Bergantung pada konfigurasi Anda, pengguna dapat memilih apakah akan a) login ke layanan Anda dengan akun yang sudah ada yang tidak menggunakan Login dengan Google atau b) membuat akun baru menggunakan penyedia lain. Untuk informasi selengkapnya tentang alur OAuth, lihat panduan konsep penautan OAuth.

Setelah memverifikasi kredensial pengguna, layanan Anda akan menampilkan token akses dan token refresh ke Google. Identitas pengguna di Action Anda sekarang ditautkan ke akun non-Google. Permintaan asli pengguna (“Pesan seperti biasa”) cocok dengan intent pengguna order_drink. Webhook Anda kemudian menangani fulfillment intent yang cocok dan mengkueri database untuk urutan [e-mail] biasa, yang belum ada karena pengguna baru. Action Anda kemudian dapat menanyakan kepada pengguna apa yang ingin mereka pesan atau meminta mereka menyiapkan pesanan seperti biasanya.

Alur dengan pembuatan akun suara dinonaktifkan

Bagian ini menjelaskan alur penautan akun yang dapat terjadi jika Anda menonaktifkan pembuatan akun melalui suara.

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

Alur 4: Informasi pengguna tidak ada

Anda tidak mengaktifkan pembuatan akun melalui suara dan pengguna tidak ada di backend Anda, sehingga alur OAuth standar dimulai. Asisten akan membuka endpoint otorisasi Anda di browser pengguna (jika alurnya dimulai di perangkat khusus suara, Google akan mentransfer eksekusi ke perangkat dengan layar). Pengguna dapat memilih untuk a) login dengan penyedia lain, jika mereka telah mendaftar ke layanan Anda dengan akun lain, atau b) membuat akun baru dengan penyedia yang berbeda. Untuk informasi selengkapnya tentang alur OAuth, lihat panduan konsep penautan OAuth.

Setelah memverifikasi kredensial pengguna, layanan Anda akan menampilkan token akses dan token refresh ke Google. Identitas pengguna di Action Anda sekarang ditautkan ke akun non-Google. Permintaan asli pengguna (“Pesan seperti biasa”) cocok dengan intent pengguna order_drink. Webhook Anda kemudian menangani fulfillment intent yang cocok dan mengkueri database untuk urutan [e-mail] biasa, yang belum ada karena pengguna baru. Action Anda kemudian dapat meminta pengguna untuk menyiapkan urutan mereka yang biasa.