Penautan akun dengan OAuth

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

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
• The token exchange endpoint, which is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

Note: Please choose which OAuth 2.0 flow you want to implement. If needed, the content of this guide reloads to adapt to your choice.

Auth code Implicit flow

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 persetujuan dari pengguna untuk akses data. Endpoint otorisasi menampilkan proses login UI untuk pengguna yang belum login dan mencatat izin meminta akses. Endpoint kedua adalah endpoint pertukaran token, yang digunakan untuk memperoleh string terenkripsi yang disebut token yang memberi otorisasi kepada pengguna Action untuk mengakses layanan Anda.

Jika Action Anda perlu memanggil salah satu API layanan Anda, Google akan menggunakan endpoint bersama-sama untuk mendapatkan izin dari pengguna Anda untuk memanggil API ini nama Anda.

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 dieksekusi ke ponsel.

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

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

3. Layanan Anda membuat kode otorisasi dan mengembalikannya ke Google dengan mengalihkan browser pengguna kembali ke Google dengan kode otorisasi dilampirkan pada permintaan.

4. Google mengirimkan kode otorisasi ke endpoint pertukaran token Anda, yang akan memverifikasi keaslian kode dan menampilkan token akses serta token refresh. Token akses adalah token berumur pendek yang dibutuhkan layanan Anda diterima sebagai kredensial untuk mengakses API. Token refresh berumur panjang yang dapat disimpan dan digunakan Google untuk mendapatkan token akses baru ketika berakhir.

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

Menangani permintaan otorisasi

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

Parameter endpoint otorisasi
client_id	Client ID Google yang Anda daftarkan dengan Google.
redirect_uri	URL tempat Anda mengirim respons atas permintaan ini.
state	Nilai pembukuan yang diteruskan kembali ke Google tanpa berubah dalam URI pengalihan.
scope	Opsional: Serangkaian string cakupan yang dipisahkan spasi yang menentukan data yang otorisasinya diminta oleh Google.
response_type	String code.

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&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 gunakan untuk mendaftar Google, dan bahwa redirect_uri cocok dengan URL alihan yang disediakan 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 sudah login ke layanan Anda. Jika pengguna tidak {i>login<i}, menyelesaikan 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 masa berlaku kode waktu, dan itu tidak boleh ditebak. Anda biasanya memberikan otorisasi kode yang berakhir masa berlakunya setelah sekitar 10 menit.

4. Konfirmasi bahwa 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 pada halaman Setelan project dari Actions Console.

5. Alihkan browser pengguna ke URL yang ditentukan oleh Parameter redirect_uri. Sertakan kode otorisasi yang baru saja dibuat dan nilai status asli yang tidak dimodifikasi saat Anda mengalihkan dengan menambahkan parameter code dan state. Berikut ini adalah contoh dari 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 token pertukaran:

• Tukar kode otorisasi dengan token akses dan token refresh
• Menukarkan 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 pengenal unik Google.
client_secret	String rahasia yang Anda daftarkan ke Google untuk layanan Anda.
grant_type	Jenis token yang dipertukarkan. Keduanya authorization_code atau refresh_token.
code	Saat grant_type=authorization_code, kode Google yang diterima dari endpoint login atau pertukaran token.
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 Google yang diterima dari endpoint pertukaran token Anda.

Tukar kode otorisasi dengan token akses dan token refresh

Setelah pengguna login dan endpoint otorisasi menampilkan otorisasi jangka pendek kode tambahan ke Google, Google mengirimkan permintaan ke endpoint pertukaran token untuk bertukar kode otorisasi untuk token akses dan token pembaruan.

Untuk permintaan ini, nilai grant_type adalah authorization_code, dan nilai sebesar code adalah nilai kode otorisasi yang sebelumnya Anda berikan kepada Google. Berikut ini 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 merespons permintaan POST yang menjalankan langkah-langkah berikut:

1. Pastikan client_id mengidentifikasi asal permintaan sebagai origin yang sah, dan bahwa client_secret sesuai dengan nilai yang diharapkan.
2. Verifikasi hal berikut:
   • Kode otorisasi valid dan masih berlaku, dan klien ID yang ditentukan dalam permintaan cocok dengan client ID yang terkait dengan kode otorisasi Anda.
   • URL yang ditentukan oleh parameter redirect_uri identik dengan nilai yang digunakan dalam permintaan otorisasi awal.
3. Jika Anda tidak dapat memverifikasi semua kriteria di atas, tampilkan permintaan HTTP Error 400 Bad Request dengan {"error": "invalid_grant"} sebagai isi.
4. Jika tidak, menggunakan ID pengguna dari kode otorisasi, buat muat ulang dan token akses. Token ini dapat berupa nilai string apa pun, tetapi harus secara unik mewakili pengguna dan klien yang menjadi sasaran token, dan mereka tidak boleh dapat ditebak. Untuk token akses, catat juga waktu habis masa berlaku token (biasanya satu jam setelah Anda menerbitkan token). Token refresh tidak akan habis masa berlakunya.
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 tersebut dan mencatat akhir masa berlaku token akses. Saat token akses berakhir, Google akan menggunakan refresh token untuk mendapatkan token akses baru dari endpoint pertukaran token Anda.

Menukarkan token refresh dengan token akses

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

Untuk permintaan ini, nilai grant_type adalah refresh_token, dan nilai dari refresh_token adalah nilai token refresh yang sebelumnya Anda berikan ke Google. Berikut ini 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

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

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

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

Catatan: Anda dapat secara opsional menampilkan refresh_token baru dalam respons Anda. Sebagai informasi selengkapnya tentang kapan menampilkan refresh_token baru lebih direkomendasikan, 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.