Menerapkan server OAuth 2.0

Setiap Action smart home harus menyertakan mekanisme untuk mengautentikasi pengguna.

Autentikasi memungkinkan Anda menautkan Akun Google pengguna dengan akun pengguna di sistem autentikasi Anda. Hal ini memungkinkan Anda mengidentifikasi pengguna saat fulfillment Anda menerima intent smart home. Google smart home hanya mendukung OAuth dengan alur kode otorisasi.

Halaman ini menjelaskan cara menyiapkan server OAuth 2.0 agar berfungsi dengan Action smart home Anda.

Penautan Akun Google dengan OAuth

In the authorization code flow, you need two endpoints:

  • The authorization endpoint, which presents the sign-in UI to your users that aren't already signed in. The authorization endpoint also creates a short-lived authorization code to record users' consent to the requested access.

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

Design guidelines

This section describes the design requirements and recommendations for the user screen that you host for OAuth linking flows. After it's called by Google's app, your platform displays a sign in to Google page and account linking consent screen to the user. The user is directed back to Google's app after giving their consent to link accounts.

This figure shows the steps for a user to link their Google account to your authentication system. The first screenshot shows user-initiated linking from your platform. The second image shows user sign-in to Google, while the third shows the user consent and confirmation for linking their Google account with your app. The final screenshot shows a successfully linked user account in the Google app.
Figure 1. Account linking user sign in to Google and consent screens.

Requirements

  1. You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.
  2. You must have a Google authorization statement such as "By signing in, you are authorizing Google to control your devices." See the Google Device Control Authorization section of the Google Home Developer Policies.
  3. You must provide a way for users to go back or cancel, if they choose not to link.
  4. You must open the Web OAuth linking page and ensure users have a clear method for signing in to their Google Account, such as fields for their username and password. Don't use the Google Sign-In (GSI) method that enables users to link without being taken to the Web OAuth Linking page. It is a violation of Google policy.

Recommendations

We recommend that you do the following:

  1. Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.

  2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

  3. Clear call-to-action. State a clear call-to-action on your consent screen, such as “Agree and link.” This is because users need to understand what data they're required to share with Google to link their accounts.

  4. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

  5. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

    • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking.

  6. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

Alur kode otorisasi

Implementasi server OAuth 2.0 untuk alur kode otorisasi terdiri dari dua endpoint, yang disediakan oleh layanan Anda oleh 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 untuk mengakses layanan Anda.

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

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

  1. Google membuka endpoint otorisasi Anda di browser pengguna. Jika alur dimulai pada perangkat khusus suara untuk suatu Tindakan, Google akan mentransfer eksekusi 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 akan membuat kode otorisasi dan menampilkannya ke Google. Untuk melakukannya, alihkan kembali browser pengguna 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 dan token refresh. Token akses adalah token berumur pendek yang diterima layanan Anda sebagai kredensial untuk mengakses API. Token refresh adalah token berumur panjang yang dapat disimpan dan digunakan oleh 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.

Menangani permintaan otorisasi

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

Parameter endpoint otorisasi
client_id Client ID yang Anda tetapkan untuk Google.
redirect_uri URL yang akan dikirimi respons.
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 diminta otorisasi oleh Google.
response_type Jenis nilai yang akan ditampilkan dalam respons. Untuk alur kode otorisasi OAuth 2.0, jenis responsnya selalu code.
user_locale Setelan bahasa Akun Google dalam format RFC5646, yang digunakan untuk melokalkan konten dalam bahasa pilihan pengguna.

Misalnya, jika endpoint otorisasi Anda tersedia di https://myservice.example.com/auth, permintaan 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

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

  1. Verifikasi bahwa client_id cocok dengan Client ID yang Anda tetapkan ke 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, pastikan juga bahwa response_type adalah code.
  2. Periksa apakah pengguna login ke layanan Anda. Jika pengguna tidak login, selesaikan alur login atau pendaftaran layanan Anda.
  3. Buat kode otorisasi untuk digunakan Google dalam mengakses API Anda. Kode otorisasi dapat berupa nilai string apa pun, tetapi harus mewakili pengguna secara unik, klien yang ditujukan untuk token, dan masa berlaku kode, serta tidak dapat ditebak. Biasanya, Anda akan mengeluarkan kode otorisasi yang masa berlakunya berakhir 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 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:

  • Tukar kode otorisasi untuk token akses dan token refresh
  • Token refresh Exchange untuk 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. Pilihannya adalah authorization_code atau refresh_token.
code Jika grant_type=authorization_code, parameter ini adalah kode yang diterima Google dari endpoint pertukaran token atau login.
redirect_uri Jika grant_type=authorization_code, parameter ini adalah URL yang digunakan dalam permintaan otorisasi awal.
refresh_token Jika grant_type=refresh_token, parameter ini adalah token refresh yang diterima Google dari endpoint pertukaran token Anda.

Tukar kode otorisasi untuk token akses dan token refresh

Setelah pengguna login dan endpoint otorisasi Anda menampilkan kode otorisasi yang berumur pendek ke Google, Google akan mengirimkan permintaan ke endpoint pertukaran token Anda guna 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 dengan menjalankan langkah-langkah berikut:

  1. Pastikan client_id mengidentifikasi asal permintaan sebagai asal yang diotorisasi, dan bahwa client_secret cocok dengan nilai yang diharapkan.
  2. Pastikan kode otorisasi valid dan masa berlakunya belum habis, serta client ID yang ditentukan dalam permintaan cocok dengan client ID yang terkait dengan kode otorisasi.
  3. Pastikan URL yang ditentukan oleh parameter redirect_uri sama dengan nilai yang digunakan dalam permintaan otorisasi awal.
  4. Jika Anda tidak dapat memverifikasi semua kriteria di atas, tampilkan error Permintaan HTTP 400 yang buruk dengan {"error": "invalid_grant"} sebagai isi pesan.
  5. Jika tidak, gunakan ID pengguna dari kode otorisasi untuk membuat token refresh dan token akses. Token ini dapat berupa nilai string apa pun, tetapi harus secara unik mewakili pengguna dan klien yang dituju token tersebut, dan tidak boleh ditebak. Untuk token akses, catat juga waktu habis masa berlaku token, yang biasanya satu jam setelah Anda menerbitkan token. Token refresh tidak akan habis masa berlakunya.
  6. 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 serta mencatat masa berlaku token akses berakhir. Setelah masa berlaku token akses berakhir, Google akan menggunakan token refresh untuk mendapatkan token akses baru dari endpoint pertukaran token Anda.

Token refresh Exchange untuk token akses

Setelah masa berlaku token akses berakhir, Google akan mengirimkan permintaan ke endpoint pertukaran token untuk menukarkan 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 dengan menjalankan langkah-langkah berikut:

  1. Pastikan client_id mengidentifikasi asal permintaan sebagai Google, dan client_secret cocok dengan nilai yang diharapkan.
  2. Verifikasikan bahwa 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 Permintaan HTTP 400 yang buruk dengan {"error": "invalid_grant"} sebagai isi pesan.
  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 dituju token tersebut, dan 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 respons HTTPS: 
    {
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

userinfo endpoint request headers
Authorization header The access token of type Bearer.

For example, if your userinfo endpoint is available at https://myservice.example.com/userinfo, a request might look like the following:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

For your userinfo endpoint to handle requests, do the following steps:

  1. Extract access token from the Authorization header and return information for the user associated with the access token.
  2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response: 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

  3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response: 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
    If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

    userinfo endpoint response
    sub A unique ID that identifies the user in your system.
    email Email address of the user.
    given_name Optional: First name of the user.
    family_name Optional: Last name of the user.
    name Optional: Full name of the user.
    picture Optional: Profile picture of the user.
Sebelumnya
Checklist developer
Berikutnya
Buat project Actions