Penautan akun dengan OAuth

Jenis penautan OAuth mendukung dua alur OAuth 2.0 standar industri, yaitu alur kode implisit dan otorisasi.

在隐式代码流程中，Google 会在用户浏览器中打开您的授权端点。成功登录后，系统会向 Google 返回长期访问令牌。现在，从 Google 助理向你的 Action 发送的每个请求中都包含此访问令牌。

在授权代码流程中，您需要两个端点：

• 授权端点，该端点负责向尚未登录的用户显示登录界面，并以短期授权代码的形式记录所请求的访问。
• 令牌交换端点，负责两种类型的交换：
  1. 将授权代码交换为长期刷新令牌和短期访问令牌。用户完成帐号关联流程后，系统会进行这种交换。
  2. 将长期刷新令牌换成短期访问令牌。Google 需要新访问令牌时，由于此令牌已过期，因此会进行此交换。

虽然隐式代码流程的实现更简单，但 Google 建议通过隐式流程发出的访问令牌永远不会过期，因为将令牌过期与隐式流程一起使用会强制用户再次关联其帐号。如果出于安全考虑需要令牌到期，强烈建议您考虑使用身份验证代码流程。

Menerapkan penautan akun OAuth

Mengonfigurasi project

Untuk mengonfigurasi project Anda agar menggunakan penautan OAuth, ikuti langkah-langkah berikut:

1. Buka Konsol Actions, lalu pilih project yang ingin Anda gunakan.
2. Klik tab Kembangkan, lalu pilih Penautan akun.
3. Aktifkan tombol di samping Penautan akun.
4. Di bagian Pembuatan akun, pilih Tidak, saya hanya ingin mengizinkan pembuatan akun di situs saya.

5. Di Jenis penautan, pilih OAuth dan Implisit.

   

6. Di Informasi Klien:

   • Tetapkan nilai ke Client ID yang dikeluarkan oleh Actions on Google untuk mengidentifikasi permintaan yang berasal dari Google.
   • Masukkan URL untuk endpoint Otorisasi dan Pertukaran Token Anda.

6. Klik Simpan.

Menerapkan server OAuth Anda

Untuk mendukung alur implisit OAuth 2.0, layanan Anda membuat otorisasi endpoint yang tersedia melalui HTTPS. Endpoint ini bertanggung jawab untuk mengotentikasi dan mendapatkan izin dari pengguna untuk akses data. Endpoint otorisasi menampilkan UI login kepada pengguna Anda yang belum login dan merekam menyetujui akses yang diminta.

Jika Action Anda perlu memanggil salah satu API yang diotorisasi layanan Anda, Google akan menggunakan endpoint ini guna mendapatkan izin dari pengguna untuk memanggil API ini di nama Anda.

Sesi alur implisit OAuth 2.0 umum yang dimulai oleh Google memiliki alur berikut:

1. Google akan membuka endpoint otorisasi Anda di browser pengguna. Tujuan pengguna masuk jika belum masuk, dan memberikan izin kepada Google untuk mengakses data mereka dengan API Anda jika mereka belum memberikan izin.
2. Layanan Anda membuat token akses dan mengembalikannya ke Google dengan mengalihkan browser pengguna kembali ke Google dengan token akses dilampirkan pada permintaan.
3. Google memanggil API layanan Anda, dan melampirkan token akses tersebut dengan setiap permintaan. Layanan Anda memverifikasi bahwa token akses tersebut memberikan untuk mengakses API, lalu menyelesaikan panggilan API.

Menangani permintaan otorisasi

Saat Action Anda perlu melakukan penautan akun melalui alur implisit OAuth 2.0, Google mengirim pengguna ke endpoint otorisasi Anda dengan permintaan yang mencakup parameter berikut:

Misalnya, jika endpoint otorisasi Anda tersedia di https://myservice.example.com/auth, permintaan akan terlihat seperti:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

Agar endpoint otorisasi Anda dapat menangani permintaan login, lakukan langkah-langkah berikut:

1. Verifikasi nilai client_id dan redirect_uri untuk mencegah pemberian akses ke aplikasi klien yang tidak diinginkan atau salah dikonfigurasi:

   • Konfirmasi bahwa client_id cocok dengan client ID Anda ditetapkan ke Google.
   • Konfirmasi bahwa URL yang ditentukan oleh redirect_uri parameter memiliki bentuk berikut:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID adalah ID yang ditemukan di halaman Setelan project dari Actions Console.

2. Periksa apakah pengguna sudah login ke layanan Anda. Jika pengguna tidak login di layanan Anda, selesaikan proses login atau pendaftaran.

3. Buat token akses yang akan digunakan Google untuk mengakses API Anda. Tujuan token akses dapat berupa nilai string apa pun, tetapi harus secara unik mewakili klien dan klien yang menjadi tujuan token, dan tidak boleh ditebak.

4. Mengirim respons HTTP yang mengalihkan browser pengguna ke URL yang ditentukan oleh parameter redirect_uri. Sertakan semua parameter berikut dalam fragmen URL:

   • access_token: token akses yang baru saja Anda buat
   • token_type: string bearer
   • state: nilai status yang tidak dimodifikasi dari aslinya minta Berikut adalah contoh URL yang dihasilkan:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Pengendali pengalihan OAuth 2.0 Google akan menerima token akses dan mengonfirmasi bahwa nilai state tidak berubah. Setelah Google mendapatkan token akses untuk layanan Anda, Google akan melampirkan token tersebut ke panggilan berikutnya ke Action Anda sebagai bagian dari AppRequest.

Mendesain antarmuka pengguna suara untuk alur autentikasi

Periksa apakah pengguna sudah diverifikasi dan mulai alur penautan akun

1. Buka project Actions Builder Anda di Konsol Actions.
2. Buat adegan baru untuk memulai penautan akun di Action Anda:
   1. Klik Adegan.
   2. Klik ikon tambahkan (+) untuk menambahkan adegan baru.
3. Di adegan yang baru dibuat, klik ikon add tambah untuk Kondisi.
4. Tambahkan kondisi yang memeriksa apakah pengguna yang terkait dengan percakapan adalah pengguna terverifikasi. Jika pemeriksaan gagal, Action Anda tidak dapat melakukan penautan akun selama percakapan, dan harus kembali ke penyediaan akses ke fungsi yang tidak memerlukan penautan akun.
   1. Di kolom Enter new expression pada bagian Kondisi, masukkan logika berikut: user.verificationStatus != "VERIFIED"
   2. Di bagian Transisi, pilih adegan yang tidak memerlukan penautan akun atau adegan yang merupakan titik entri ke fungsi khusus tamu.

1. Klik ikon tambah add untuk Kondisi.
2. Tambahkan kondisi untuk memicu alur penautan akun jika pengguna tidak memiliki identitas terkait.
   1. Di kolom Enter new expression pada bagian Kondisi, masukkan logika berikut: user.verificationStatus == "VERIFIED"
   2. Di bagian Transisi, pilih adegan sistem Penautan Akun.
   3. Klik Simpan.

Setelah disimpan, adegan sistem penautan akun baru bernama <SceneName>_AccountLinking ditambahkan ke project Anda.

Menyesuaikan adegan penautan akun

1. Di bagian Scenes, pilih adegan sistem penautan akun.
2. Klik Kirim perintah dan tambahkan kalimat singkat untuk menjelaskan kepada pengguna mengapa Tindakan perlu mengakses identitas mereka (misalnya "Untuk menyimpan preferensi Anda").
3. Klik Simpan.

1. Di bagian Kondisi, klik Jika pengguna berhasil menyelesaikan penautan akun.
2. Konfigurasi cara alur harus dilanjutkan jika pengguna setuju untuk menautkan akunnya. Misalnya, panggil webhook untuk memproses logika bisnis kustom yang diperlukan dan kembali ke scene asal.
3. Klik Simpan.

1. Di bagian Kondisi, klik Jika pengguna membatalkan atau menutup penautan akun.
2. Konfigurasi cara alur harus dilanjutkan jika pengguna tidak setuju untuk menautkan akunnya. Misalnya, kirim pesan konfirmasi dan alihkan ke adegan yang menyediakan fungsi yang tidak memerlukan penautan akun.
3. Klik Simpan.

1. Di bagian Kondisi, klik Jika terjadi error sistem atau jaringan.
2. Konfigurasi cara alur harus dilanjutkan jika alur penautan akun tidak dapat diselesaikan karena error sistem atau jaringan. Misalnya, kirim pesan konfirmasi dan alihkan ke adegan yang menyediakan fungsi yang tidak memerlukan penautan akun.
3. Klik Simpan.

Menangani permintaan akses data

Jika permintaan Asisten berisi token akses, periksa terlebih dahulu apakah token akses valid (dan tidak kedaluwarsa), lalu ambil akun pengguna terkait dari database Anda.