Overview

Every smart home Action must include a mechanism for authenticating users.

Authentication allows you to link your users' Google accounts with user accounts in your authentication system. This allows you to identify your users when your fulfillment receives a smart home intent. Google smart home only supports OAuth with an authorization code flow.

Pedoman desain

Bagian ini menjelaskan persyaratan desain dan rekomendasi untuk layar persetujuan penautan akun App Flip. Setelah Google memanggil aplikasi Anda, aplikasi Anda menampilkan layar persetujuan kepada pengguna.

Persyaratan

  1. Anda harus menyampaikan bahwa akun pengguna sedang ditautkan ke Google, bukan ke produk Google tertentu, seperti Google Home atau Asisten Google.

Rekomendasi

Kami menyarankan Anda melakukan hal berikut:

  1. Tampilkan Kebijakan Privasi Google. Sertakan tautan ke Kebijakan Privasi Google di layar persetujuan.

  2. Data untuk dibagikan. Gunakan bahasa yang jelas dan ringkas untuk memberi tahu pengguna data apa yang dibutuhkan Google mereka dan mengapa.

  3. Ajakan bertindak yang jelas. Nyatakan ajakan bertindak yang jelas di layar persetujuan Anda, seperti "Setuju dan tautkan". Ini karena pengguna perlu memahami data apa yang mereka butuhkan untuk dibagikan dengan Google untuk menautkan akun mereka.

  4. Kemampuan untuk membatalkan. Sediakan cara bagi pengguna untuk kembali atau membatalkan, jika mereka memilih untuk tidak menautkan.

  5. Kemampuan untuk membatalkan tautan. Tawarkan mekanisme bagi pengguna untuk membatalkan tautan, seperti URL ke pengaturan akun mereka di platform Anda. Atau, Anda dapat menyertakan tautan ke Akun Google tempat pengguna dapat mengelola akun tertaut mereka.

  6. Kemampuan untuk mengubah akun pengguna. Sarankan metode bagi pengguna untuk mengalihkan akun mereka. Ini sangat bermanfaat jika pengguna cenderung memiliki banyak akun.

    • Jika pengguna harus menutup layar persetujuan untuk beralih akun, kirimkan kesalahan yang dapat dipulihkan ke Google sehingga pengguna dapat masuk ke akun yang diinginkan dengan penautan OAuth dan alur implisit .
  7. Sertakan logo Anda. Tampilkan logo perusahaan Anda di layar persetujuan. Gunakan pedoman gaya Anda untuk menempatkan logo Anda. Jika Anda juga ingin menampilkan logo Google, lihat Logo dan merek dagang .

Gambar ini menunjukkan contoh layar persetujuan dengan keterangan tentang persyaratan individu dan rekomendasi yang harus diikuti saat Anda mendesain layar persetujuan pengguna.
Gambar 2. Panduan desain layar persetujuan penautan akun.

Implement OAuth account linking

To implement OAuth account linking in your smart home Action, you must do the following:

  1. Implement your OAuth 2.0 server.
  2. Configure account linking in the Actions console.

Implement your OAuth 2.0 server

This section describes how to set up your OAuth 2.0 server so that it works with your smart home Action.

Implementasi server OAuth 2.0 dari aliran kode otorisasi terdiri dari dua titik akhir, yang disediakan oleh layanan Anda oleh HTTPS. Titik akhir pertama adalah titik akhir otorisasi, yang bertanggung jawab untuk menemukan atau mendapatkan persetujuan dari pengguna untuk akses data. Titik akhir otorisasi menampilkan UI masuk kepada pengguna Anda yang belum masuk dan mencatat persetujuan untuk akses yang diminta. Titik akhir kedua adalah titik akhir pertukaran token, yang digunakan untuk mendapatkan string terenkripsi, yang disebut token, yang memberi otorisasi kepada pengguna untuk mengakses layanan Anda.

Saat aplikasi Google perlu memanggil salah satu API layanan Anda, Google menggunakan titik akhir ini bersama-sama untuk mendapatkan izin dari pengguna Anda untuk memanggil API ini atas nama mereka.

Sesi aliran kode otorisasi OAuth 2.0 yang dimulai oleh Google memiliki aliran berikut:

  1. Google membuka titik akhir otorisasi Anda di browser pengguna. Jika aliran dimulai pada perangkat khusus suara untuk suatu Tindakan, Google mentransfer eksekusi ke telepon.
  2. Pengguna masuk, jika belum masuk, dan memberi Google izin untuk mengakses data mereka dengan API Anda, jika mereka belum memberikan izin.
  3. Layanan Anda membuat kode otorisasi dan mengembalikannya ke Google. Untuk melakukannya, alihkan kembali browser pengguna ke Google dengan kode otorisasi yang dilampirkan ke permintaan.
  4. Google mengirimkan kode otorisasi ke titik akhir pertukaran token Anda, yang memverifikasi keaslian kode dan mengembalikan token akses dan token penyegaran . Token akses adalah token berumur pendek yang diterima layanan Anda sebagai kredensial untuk mengakses API. Token penyegaran adalah token berumur panjang yang dapat disimpan dan digunakan Google untuk memperoleh token akses baru ketika masa berlakunya habis.
  5. Setelah pengguna menyelesaikan alur penautan akun, setiap permintaan berikutnya yang dikirim dari Google berisi token akses.

Tangani permintaan otorisasi

Saat Anda perlu melakukan penautan akun menggunakan alur kode otorisasi OAuth 2.0, Google mengarahkan pengguna ke titik akhir otorisasi Anda dengan permintaan yang menyertakan parameter berikut:

Parameter titik akhir otorisasi
client_id ID klien Google yang Anda daftarkan dengan Google.
redirect_uri URL yang Anda kirimi tanggapan atas permintaan ini.
state Nilai pembukuan yang dikembalikan ke Google tidak berubah di URI pengalihan.
scope Opsional: Rangkaian string cakupan yang dipisahkan spasi, yang menentukan data yang diminta otorisasi oleh Google.
response_type Jenis nilai yang akan dikembalikan dalam respons. Untuk alur kode otorisasi OAuth 2.0, jenis respons selalu berupa code .
user_locale Setelan bahasa Akun Google dalam format RFC5646 , digunakan untuk melokalkan konten Anda ke bahasa pilihan pengguna.

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

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

Agar titik akhir otorisasi Anda menangani permintaan masuk, lakukan langkah-langkah berikut:

  1. Verifikasikan bahwa client_id cocok dengan ID klien Google yang Anda daftarkan ke Google, dan bahwa redirect_uri cocok dengan URL pengalihan yang disediakan oleh Google untuk layanan Anda. Pemeriksaan ini penting untuk mencegah pemberian akses ke aplikasi klien yang tidak diinginkan atau salah konfigurasi. Jika Anda mendukung beberapa aliran OAuth 2.0, pastikan juga bahwa response_type adalah code .
  2. Periksa apakah pengguna masuk ke layanan Anda. Jika pengguna tidak login, selesaikan proses login atau pendaftaran layanan Anda.
  3. Buat kode otorisasi untuk digunakan Google untuk mengakses API Anda. Kode otorisasi dapat berupa nilai string apa pun, tetapi harus mewakili pengguna secara unik, token untuk klien, dan waktu kedaluwarsa kode, serta tidak boleh dapat ditebak. Anda biasanya mengeluarkan kode otorisasi yang kedaluwarsa setelah sekitar 10 menit.
  4. Konfirmasikan bahwa URL yang ditentukan oleh parameter redirect_uri memiliki format berikut:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  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 tidak diubah saat Anda mengalihkan dengan menambahkan code dan parameter state . Berikut adalah contoh URL yang dihasilkan:
    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Tangani permintaan pertukaran token

Titik akhir pertukaran token layanan Anda bertanggung jawab atas dua jenis pertukaran token:

  • Tukarkan kode otorisasi untuk token akses dan segarkan token
  • Tukarkan token penyegaran untuk token akses

Permintaan pertukaran token mencakup parameter berikut:

Parameter titik akhir pertukaran token
client_id Sebuah 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 ditukar. Baik itu authorization_code atau refresh_token .
code Jika grant_type=authorization_code , parameter ini adalah kode yang diterima Google dari proses masuk atau titik akhir 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 , parameter ini adalah token penyegaran yang diterima Google dari titik akhir pertukaran token Anda.
Tukarkan kode otorisasi untuk token akses dan segarkan token

Setelah pengguna masuk dan titik akhir otorisasi Anda mengembalikan kode otorisasi berumur pendek ke Google, Google mengirimkan permintaan ke titik akhir pertukaran token Anda untuk menukar kode otorisasi dengan token akses dan token penyegaran.

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

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 penyegaran, titik akhir pertukaran token Anda menanggapi permintaan POST dengan menjalankan langkah-langkah berikut:

  1. Verifikasi bahwa client_id mengidentifikasi asal permintaan sebagai asal resmi, dan client_secret cocok dengan nilai yang diharapkan.
  2. Verifikasikan bahwa kode otorisasi valid dan tidak kedaluwarsa, dan ID klien yang ditentukan dalam permintaan cocok dengan ID klien yang terkait dengan kode otorisasi.
  3. Konfirmasikan bahwa URL yang ditentukan oleh parameter redirect_uri identik dengan nilai yang digunakan dalam permintaan otorisasi awal.
  4. Jika Anda tidak dapat memverifikasi semua kriteria di atas, kembalikan kesalahan HTTP 400 Bad Request dengan isi {"error": "invalid_grant"} .
  5. Jika tidak, gunakan ID pengguna dari kode otorisasi untuk membuat token penyegaran dan token akses. Token ini dapat berupa nilai string apa pun, tetapi harus secara unik mewakili pengguna dan klien tempat token tersebut, dan tidak boleh dapat ditebak. Untuk token akses, catat juga waktu kedaluwarsa token, yang biasanya satu jam setelah Anda menerbitkan token. Segarkan token tidak kedaluwarsa.
  6. Kembalikan objek JSON berikut di badan respons HTTPS:
    {
    "token_type": "Bearer",
    "access_token": "ACCESS_TOKEN",
    "refresh_token": "REFRESH_TOKEN",
    "expires_in": SECONDS_TO_EXPIRATION
    }
    

Google menyimpan token akses dan token penyegaran untuk pengguna dan mencatat kedaluwarsa token akses. Saat token akses kedaluwarsa, Google menggunakan token penyegaran untuk mendapatkan token akses baru dari titik akhir pertukaran token Anda.

Tukarkan token penyegaran untuk token akses

Saat token akses kedaluwarsa, Google mengirimkan permintaan ke titik akhir pertukaran token Anda untuk menukar token penyegaran 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 kepada Google. Berikut ini adalah contoh permintaan untuk menukar token penyegaran 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 penyegaran dengan token akses, titik akhir pertukaran token Anda menanggapi permintaan POST dengan menjalankan langkah-langkah berikut:

  1. Verifikasi bahwa client_id mengidentifikasi asal permintaan sebagai Google, dan bahwa client_secret cocok dengan nilai yang diharapkan.
  2. Verifikasikan bahwa token penyegaran valid, dan bahwa ID klien yang ditentukan dalam permintaan cocok dengan ID klien yang terkait dengan token penyegaran.
  3. Jika Anda tidak dapat memverifikasi semua kriteria di atas, kembalikan kesalahan HTTP 400 Bad Request dengan isi {"error": "invalid_grant"} .
  4. Jika tidak, gunakan ID pengguna dari token penyegaran untuk membuat token akses. Token ini dapat berupa nilai string apa pun, tetapi harus secara unik mewakili pengguna dan klien tempat token tersebut, dan tidak boleh dapat ditebak. Untuk token akses, catat juga waktu kedaluwarsa token, biasanya satu jam setelah Anda menerbitkan token.
  5. Kembalikan objek JSON berikut di badan respons HTTPS:
    {
    "token_type": "Bearer",
    "access_token": " ACCESS_TOKEN ",
    "expires_in": SECONDS_TO_EXPIRATION
    }

Configure account linking in the console

To set up account linking in the Actions console, follow these steps:

  1. Go to the Actions console.
  2. Select your smart home Action project.
  3. Click the Develop tab. Then, click Account linking in the left navigation.
  4. Fill out all the fields under OAuth Client information. Click Next.
  5. Click Save.

Next steps (optional)

Once you have an OAuth 2.0 implementation, you can optionally configure OAuth-based App Flip, which allows your users to more quickly link their accounts in your authentication system to their Google accounts. For App Flip implementation instructions, see OAuth-based App Flip.