Penautan akun dengan OAuth (Dialogflow)

Jenis penautan OAuth mendukung dua alur OAuth 2.0 standar industri, yaitu alur implisit dan alur kode 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.

Terapkan penautan akun OAuth

Mengonfigurasi project

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

1. Buka Actions Console 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. Pada Linking type, pilih OAuth dan Implicit.

   

6. Di Informasi Klien:

   • Tetapkan nilai ke Client ID yang diterbitkan oleh Actions to Google Anda untuk mengidentifikasi permintaan yang berasal dari Google.
   • Masukkan URL untuk endpoint Otorisasi dan Token Exchange.

6. Klik Simpan.

Mengimplementasikan server OAuth

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 OAuth2, 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 pada 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.

Memulai alur autentikasi

Menggunakan intent bantuan Login Akun untuk memulai alur otentikasi. Cuplikan kode berikut menjelaskan cara mengirim respons di Dialogflow dan Actions SDK untuk menggunakan helper ini.

Dialogflow:

const {dialogflow, SignIn} = require('actions-on-google');
const app = dialogflow({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
});
// Intent that starts the account linking flow.
app.intent('Start Signin', (conv) => {
  conv.ask(new SignIn('To get your account details'));
});

@ForIntent("Start Signin")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "PLACEHOLDER"
            }
          }
        ]
      },
      "userStorage": "{\"data\":{}}",
      "systemIntent": {
        "intent": "actions.intent.SIGN_IN",
        "data": {
          "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec",
          "optContext": "To get your account details"
        }
      }
    }
  },
  "outputContexts": [
    {
      "name": "/contexts/_actions_on_google",
      "lifespanCount": 99,
      "parameters": {
        "data": "{}"
      }
    }
  ]
}

SDK Tindakan:

const {actionssdk, SignIn} = require('actions-on-google');
const app = actionssdk({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
});
// Intent that starts the account linking flow.
app.intent('actions.intent.TEXT', (conv) => {
  conv.ask(new SignIn('To get your account details'));
});

@ForIntent("actions.intent.TEXT")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "PLACEHOLDER"
              }
            }
          ]
        }
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.SIGN_IN",
          "inputValueData": {
            "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec",
            "optContext": "To get your account details"
          }
        }
      ]
    }
  ],
  "conversationToken": "{\"data\":{}}",
  "userStorage": "{\"data\":{}}"
}

Menangani permintaan akses data

Jika permintaan Asisten berisi token akses, pertama-tama periksa apakah token akses valid (dan masa berlakunya belum habis), lalu ambil akun pengguna terkait dari database Anda.