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.

Menerapkan penautan akun OAuth

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

  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
}

Mendesain antarmuka pengguna suara untuk alur autentikasi

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.