Penautan akun dengan OAuth

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

Dalam alur kode implisit, Google membuka endpoint otorisasi Anda di browser pengguna. Setelah berhasil login, Anda akan menampilkan token akses berumur panjang ke Google. Token akses ini sekarang disertakan di setiap permintaan yang dikirim dari Asisten ke Action.

Dalam alur kode otorisasi, Anda membutuhkan dua endpoint:

• Endpoint otorisasi, yang bertanggung jawab untuk menampilkan UI login kepada pengguna yang belum login, dan merekam izin untuk akses yang diminta dalam bentuk kode otorisasi yang memiliki masa aktif singkat.
• Endpoint pertukaran token, yang bertanggung jawab atas dua jenis pertukaran:
  1. Menukarkan 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. Menukarkan token refresh yang memiliki masa aktif lama dengan token akses yang memiliki masa aktif singkat. Pertukaran ini terjadi saat Google memerlukan token akses baru karena masa berlakunya telah berakhir.

Meskipun alur kode implisit lebih mudah diimplementasikan, Google merekomendasikan agar token akses yang dikeluarkan menggunakan alur implisit tidak pernah kedaluwarsa, karena menggunakan masa berlaku token dengan alur implisit akan memaksa pengguna untuk menautkan akunnya lagi. Jika Anda memerlukan masa berlaku token untuk alasan keamanan, Anda harus mempertimbangkan penggunaan alur kode autentikasi.

Catatan: Pilih alur OAuth 2.0 yang ingin Anda terapkan. Jika diperlukan, konten dalam panduan ini akan dimuat ulang untuk disesuaikan dengan pilihan Anda.

Kode Auth Alur implisit

Menerapkan penautan akun OAuth

Catatan: Jika Anda menerapkan penautan akun untuk menangani informasi keuangan, perlu diperhatikan bahwa kebijakan tambahan mungkin berlaku untuk Action Anda. Kami membutuhkan waktu hingga enam minggu untuk meninjau Action dengan penautan akun untuk mendapatkan informasi keuangan, jadi perhitungkan waktu tersebut saat merencanakan jadwal rilis Anda. Untuk memudahkan proses peninjauan, pastikan Anda mematuhi kebijakan jasa keuangan sebelum mengirimkan Action untuk ditinjau.

Mengonfigurasi project

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

1. Buka Konsol Actions dan pilih project yang ingin Anda gunakan.
2. Klik tab Develop dan pilih Account linking.
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 Kode otorisasi.

   

6. Di Informasi Klien:

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

Catatan: Jika Anda ingin client ID dan rahasia dikirim sebagai string berenkode base64, klik panah drop-down di sebelah Configure your client (optional), lalu centang kotak Google to mentransmisikan clientID dan secret via HTTP basic auth header.

6. Klik Simpan.

Menerapkan server OAuth

Implementasi server OAuth 2.0 dari alur kode otorisasi terdiri dari dua endpoint, yang disediakan oleh layanan Anda melalui HTTPS. Endpoint pertama adalah endpoint otorisasi, yang bertanggung jawab untuk menemukan atau mendapatkan izin dari pengguna untuk akses data. Endpoint otorisasi menampilkan UI login kepada pengguna yang belum login dan mencatat izin untuk akses yang diminta. Endpoint kedua adalah endpoint pertukaran token, yang digunakan untuk mendapatkan string terenkripsi yang disebut token, yang mengizinkan pengguna Action untuk mengakses layanan Anda.

Saat Action Anda perlu memanggil salah satu API layanan Anda, Google akan menggunakan endpoint ini secara bersamaan untuk mendapatkan izin dari pengguna Anda guna memanggil API ini atas nama mereka.

Sesi alur kode autentikasi OAuth 2.0 yang dimulai oleh Google memiliki alur berikut:

1. Google akan membuka endpoint otorisasi Anda di browser pengguna. Jika alur dimulai di perangkat khusus suara untuk Action, Google akan mentransfer eksekusi ke ponsel.

2. Pengguna akan login (jika belum login) dan memberi Google izin untuk mengakses data mereka dengan API Anda jika mereka belum memberikan izin.

   Catatan: Anda harus memberitahukan bahwa akun pengguna ditautkan ke Google, bukan ke produk Google tertentu, seperti Google Home atau Asisten Google.

3. Layanan Anda membuat kode otorisasi, lalu mengembalikannya ke Google dengan mengalihkan browser pengguna kembali ke Google dengan kode otorisasi yang disertakan pada permintaan.

4. 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.

5. Setelah pengguna menyelesaikan alur penautan akun, setiap permintaan berikutnya yang dikirim dari Asisten ke webhook fulfillment Anda berisi token akses.

Menangani permintaan otorisasi

Saat Action Anda perlu melakukan penautan akun melalui alur kode otorisasi OAuth 2.0, Google akan mengirimkan pengguna ke endpoint otorisasi Anda dengan permintaan yang menyertakan parameter berikut:

Parameter endpoint otorisasi
client_id	Client ID Google yang Anda daftarkan ke Google.
redirect_uri	URL yang Anda kirimi respons untuk permintaan ini.
state	Nilai pembukuan yang diteruskan kembali ke Google tidak berubah dalam URI pengalihan.
scope	Opsional: Kumpulan string cakupan yang dipisahkan spasi, yang menentukan data yang dimintakan otorisasi oleh Google.
response_type	String code.

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

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

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

1. Verifikasi bahwa client_id cocok dengan client ID Google yang Anda daftarkan ke Google, dan bahwa redirect_uri cocok dengan URL alihan yang diberikan oleh Google untuk layanan Anda. Pemeriksaan ini penting untuk mencegah pemberian akses ke aplikasi klien yang tidak diinginkan atau salah dikonfigurasi.

   Jika Anda mendukung beberapa alur OAuth 2.0, konfirmasi juga bahwa response_type adalah code.

2. Periksa apakah pengguna login ke layanan Anda. Jika pengguna belum login, selesaikan alur login atau pendaftaran layanan Anda.

3. Buat kode otorisasi yang akan digunakan Google untuk mengakses API Anda. Kode otorisasi dapat berupa nilai string apa pun, tetapi harus secara unik mewakili pengguna, klien yang menjadi tujuan token, dan waktu habis masa berlaku kode, serta tidak boleh dapat ditebak. Anda biasanya memberikan kode otorisasi yang habis masa berlakunya setelah sekitar 10 menit.

4. Pastikan URL yang ditentukan oleh parameter redirect_uri memiliki bentuk berikut:

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

   YOUR_PROJECT_ID adalah ID yang ditemukan di halaman Setelan project Konsol Actions.

5. Alihkan browser pengguna ke URL yang ditentukan oleh parameter redirect_uri. Sertakan kode otorisasi yang baru saja Anda buat dan nilai status asli yang belum dimodifikasi saat Anda melakukan pengalihan dengan menambahkan parameter code dan state. Berikut adalah contoh URL yang dihasilkan:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Menangani permintaan pertukaran token

Endpoint pertukaran token layanan Anda bertanggung jawab atas dua jenis pertukaran token:

• Menukar kode otorisasi dengan token akses dan token refresh
• Tukar token refresh dengan token akses

Permintaan pertukaran token mencakup parameter berikut:

Parameter endpoint pertukaran token
client_id	String yang mengidentifikasi asal permintaan sebagai Google. String ini harus terdaftar dalam sistem Anda sebagai ID unik Google.
client_secret	String rahasia yang Anda daftarkan ke Google untuk layanan Anda.
grant_type	Jenis token yang dipertukarkan. Berupa authorization_code atau refresh_token.
code	Saat grant_type=authorization_code, kode yang diterima Google dari endpoint login atau pertukaran token Anda.
redirect_uri	Jika grant_type=authorization_code, parameter ini adalah URL yang digunakan dalam permintaan otorisasi awal.
refresh_token	Saat grant_type=refresh_token, token refresh yang diterima Google dari endpoint pertukaran token Anda.

Menukar kode otorisasi dengan token akses dan token refresh

Setelah pengguna login dan endpoint otorisasi Anda menampilkan kode otorisasi berumur singkat ke Google, Google akan mengirimkan permintaan ke endpoint pertukaran token Anda untuk menukar kode otorisasi dengan token akses dan token refresh.

Untuk permintaan ini, nilai grant_type adalah authorization_code, dan nilai code adalah nilai kode otorisasi yang sebelumnya Anda berikan ke Google. Berikut adalah contoh permintaan untuk menukar kode otorisasi dengan token akses dan token refresh:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

Untuk menukar kode otorisasi dengan token akses dan token refresh, endpoint pertukaran token Anda akan merespons permintaan POST yang menjalankan langkah-langkah berikut:

1. Verifikasi bahwa client_id mengidentifikasi asal permintaan sebagai asal yang diizinkan, dan bahwa client_secret cocok dengan nilai yang diharapkan.
2. Pastikan beberapa hal berikut:
   • Kode otorisasi valid dan masih berlaku, dan client ID yang ditentukan dalam permintaan cocok dengan client ID yang terkait dengan kode otorisasi.
   • URL yang ditentukan oleh parameter redirect_uri sama dengan nilai yang digunakan dalam permintaan otorisasi awal.
3. Jika Anda tidak dapat memverifikasi semua kriteria di atas, tampilkan error HTTP 400 Bad Request dengan {"error": "invalid_grant"} sebagai isi.
4. Jika tidak, dengan menggunakan ID pengguna dari kode otorisasi, buat token refresh dan token akses. Token ini dapat berupa nilai string apa pun, tetapi harus secara unik mewakili pengguna dan klien yang menjadi tujuan token tersebut, dan tidak boleh mudah ditebak. Untuk token akses, catat juga waktu habis masa berlaku token (biasanya satu jam setelah Anda mengeluarkan token). Token refresh tidak memiliki masa berlaku.
5. Tampilkan objek JSON berikut dalam isi respons HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }
   

Google menyimpan token akses dan token refresh untuk pengguna dan mencatat masa berlaku token akses. Saat masa berlaku token akses berakhir, Google akan menggunakan token refresh untuk mendapatkan token akses baru dari endpoint pertukaran token Anda.

Tukar token refresh dengan token akses

Saat masa berlaku token akses berakhir, Google akan mengirimkan permintaan ke endpoint pertukaran token Anda untuk menukar token refresh dengan token akses baru.

Untuk permintaan ini, nilai grant_type adalah refresh_token, dan nilai refresh_token adalah nilai token refresh yang sebelumnya Anda berikan ke Google. Berikut adalah contoh permintaan untuk menukar token refresh dengan token akses:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

Untuk menukar token refresh dengan token akses, endpoint pertukaran token Anda akan merespons permintaan POST yang menjalankan langkah-langkah berikut:

1. Verifikasi bahwa client_id mengidentifikasi asal permintaan sebagai Google, dan bahwa client_secret cocok dengan nilai yang diharapkan.
2. Pastikan token refresh valid, dan client ID yang ditentukan dalam permintaan cocok dengan client ID yang terkait dengan token refresh.
3. Jika Anda tidak dapat memverifikasi semua kriteria di atas, tampilkan error HTTP 400 Bad Request dengan {"error": "invalid_grant"} sebagai isi.
4. Jika tidak, gunakan ID pengguna dari token refresh untuk membuat token akses. Token ini dapat berupa nilai string apa pun, tetapi harus secara unik mewakili pengguna dan klien yang menjadi tujuan token tersebut, dan tidak boleh ditebak. Untuk token akses, catat juga waktu habis masa berlaku token (biasanya satu jam setelah Anda mengeluarkan token).
5. Tampilkan objek JSON berikut dalam isi respons HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Catatan: Jika ingin, Anda dapat menampilkan refresh_token baru dalam respons. Untuk mengetahui informasi selengkapnya tentang kapan sebaiknya menampilkan refresh_token baru, lihat Bekerja dengan token.

Mendesain antarmuka pengguna suara untuk alur autentikasi

Peringatan: Jangan beri pengguna permintaan penautan akun wajib di awal percakapan dengan Action Anda. Sebagai gantinya, berikan alur tamu kepada pengguna yang tidak diautentikasi untuk menunjukkan cara kerja Action Anda, lalu minta penautan akun hanya jika diperlukan untuk melanjutkan. Jika pengguna keluar dari Action secara konsisten karena masalah penautan akun, Google tidak akan secara aktif mempromosikan Action, sehingga dapat menurunkan traffic pengguna Action tersebut.

Catatan: Anda harus menggunakan Actions Builder untuk membuat Action yang menerapkan penautan akun.

Periksa apakah pengguna telah diverifikasi dan mulai alur penautan akun

1. Buka project Action Builder Anda di Konsol Actions.
2. Buat scene baru untuk memulai penautan akun di Action Anda:
   1. Klik Scene.
   2. Klik ikon add (+) untuk menambahkan adegan baru.
3. Pada scene yang baru dibuat, klik ikon tambahkan 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 menyediakan 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 Transition, pilih scene yang tidak memerlukan penautan akun atau scene yang merupakan titik entri ke fungsi khusus tamu.

1. Klik ikon tambahkan 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 scene sistem Penautan Akun.
   3. Klik Simpan.

Setelah disimpan, scene sistem penautan akun baru yang disebut <SceneName>_AccountLinking akan ditambahkan ke project Anda.

Menyesuaikan adegan penautan akun

1. Di bagian Scene, pilih scene sistem penautan akun.
2. Klik Kirim perintah dan tambahkan kalimat singkat untuk menjelaskan kepada pengguna alasan Action 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 berjalan jika pengguna setuju untuk menautkan akun mereka. Misalnya, panggil webhook untuk memproses logika bisnis kustom yang diperlukan dan lakukan transisi kembali ke scene asal.
3. Klik Simpan.

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

1. Di bagian Kondisi, klik Jika terjadi error sistem atau jaringan.
2. Konfigurasikan cara alur akan dilanjutkan jika alur penautan akun tidak dapat diselesaikan karena error sistem atau jaringan. Misalnya, kirim pesan konfirmasi dan alihkan ke scene 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 belum habis masa berlakunya), lalu ambil akun pengguna terkait dari database Anda.