Penautan Akun Google dengan OAuth

Akun ditautkan menggunakan alur kode otorisasi OAuth 2.0 standar industri.

OAuth 2.1 &PKCE untuk Agen

Untuk agen AI tanpa status dan pipeline multi-modal, sebaiknya terapkan OAuth 2.1.

• PKCE (Proof Key for Code Exchange): Harus digunakan untuk mengamankan alur kode otorisasi, sehingga mencegah serangan intersepsi.
• Tidak Ada Alur Implisit: Alur implisit mengekspos token akses di URL, yang merupakan risiko keamanan untuk lingkungan agen.

Layanan Anda harus mendukung endpoint pertukaran token dan otorisasi yang sesuai dengan OAuth 2.0/2.1.

Membuat project

Untuk membuat project Anda agar dapat menggunakan penautan akun:

1. Buka Konsol Google API.
2. Klik Buat proyek.
3. Masukkan nama atau terima saran yang dibuat.
4. Konfirmasi atau edit kolom yang tersisa.
5. Klik Buat.

Untuk melihat project ID Anda:

1. Buka Konsol Google API.
2. Cari project Anda di tabel pada halaman landing. Project ID muncul di kolom ID.

Mengonfigurasi Layar Izin OAuth Anda

Proses Penautan Akun Google mencakup layar izin yang memberi tahu pengguna aplikasi yang meminta akses ke data mereka, jenis data yang diminta, dan persyaratan yang berlaku. Anda harus mengonfigurasi layar izin OAuth sebelum membuat ID klien Google API.

1. Buka halaman Layar izin OAuth di konsol API Google.
2. Jika diminta, pilih project yang baru saja Anda buat.

3. Di halaman "Layar izin OAuth", isi formulir, lalu klik tombol “Simpan”.

   Nama aplikasi: Nama aplikasi yang meminta izin. Nama harus mencerminkan aplikasi Anda secara akurat dan konsisten dengan nama aplikasi yang dilihat pengguna di tempat lain. Nama aplikasi akan ditampilkan di layar izin Penautan Akun.

   Logo aplikasi: Gambar di layar izin yang akan membantu pengguna mengenali aplikasi Anda. Logo ditampilkan di layar izin Penautan akun dan di setelan akun

   Email dukungan: Agar pengguna dapat menghubungi Anda jika ada pertanyaan tentang izin mereka.

   Cakupan untuk Google API: Cakupan memungkinkan aplikasi Anda mengakses data pribadi Google pengguna Anda. Untuk kasus penggunaan Penautan Akun Google, cakupan default (email, profil, openid) sudah cukup, Anda tidak perlu menambahkan cakupan sensitif. Secara umum, praktik terbaiknya adalah meminta cakupan secara bertahap, pada saat akses diperlukan, bukan di awal. Pelajari lebih lanjut.

   Domain yang diizinkan: Guna melindungi Anda dan pengguna Anda, Google hanya mengizinkan aplikasi yang melakukan autentikasi menggunakan OAuth untuk menggunakan Domain yang Diizinkan. Link aplikasi Anda harus dihosting di Domain yang Diotorisasi. Pelajari lebih lanjut.

   Link Halaman Beranda Aplikasi: Halaman beranda untuk aplikasi Anda. Harus dihosting di Domain yang Diotorisasi.

   Link Kebijakan Privasi Aplikasi: Ditampilkan di layar izin Penautan Akun Google. Harus dihosting di Domain yang Diotorisasi.

   Link Persyaratan Layanan Aplikasi (Opsional): Harus dihosting di Domain yang Diotorisasi.

   

   Gambar 1. Layar Izin Penautan Akun Google untuk Aplikasi fiktif, Tunery

4. Periksa "Status Verifikasi", jika aplikasi Anda memerlukan verifikasi, klik tombol "Kirim Untuk Verifikasi" untuk mengirimkan aplikasi Anda untuk diverifikasi. Lihat persyaratan verifikasi OAuth untuk mengetahui detailnya.

Mengimplementasikan 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 izin dari pengguna untuk akses data. Endpoint otorisasi menampilkan UI login kepada pengguna Anda 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 mengotorisasi pengguna untuk mengakses layanan Anda.

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

Penautan Akun Google: Alur Kode Otorisasi OAuth

Diagram urutan berikut menjelaskan interaksi antara Pengguna, Google, dan endpoint layanan Anda.

Peran dan tanggung jawab

Tabel berikut menentukan peran dan tanggung jawab aktor dalam alur OAuth Penautan Akun Google (GAL). Perhatikan bahwa di GAL, Google bertindak sebagai Klien OAuth, sedangkan layanan Anda bertindak sebagai Penyedia Identitas/Layanan.

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 di perangkat khusus suara untuk 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 membuat kode otorisasi dan menampilkannya ke Google. Untuk melakukannya, alihkan browser pengguna kembali ke Google dengan kode otorisasi yang dilampirkan ke 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 Google untuk mendapatkan token akses baru saat masa berlakunya berakhir.
5. Setelah pengguna menyelesaikan alur penautan akun, setiap permintaan berikutnya yang dikirim dari Google akan berisi token akses.

Resep Implementasi

Ikuti langkah-langkah berikut untuk mengimplementasikan alur Kode Otorisasi.

Langkah 1: Menangani permintaan otorisasi

Saat Google memulai penautan akun, Google akan mengalihkan pengguna ke endpoint otorisasi Anda. Untuk mengetahui detail kontrak protokol dan persyaratan parameter, lihat Endpoint Otorisasi.

Untuk menangani permintaan, lakukan tindakan berikut:

1. Validasi permintaan:

   • Pastikan client_id cocok dengan Client ID yang ditetapkan ke Google.
   • Pastikan redirect_uri cocok dengan URL pengalihan Google yang diharapkan: none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
   • Pastikan response_type adalah code.

2. Autentikasi pengguna:

   • Periksa apakah pengguna login ke layanan Anda.
   • Jika pengguna tidak login, minta mereka untuk menyelesaikan alur login atau pendaftaran Anda.

3. Buat kode otorisasi:

   • Buat kode otorisasi unik yang tidak dapat ditebak dan terkait dengan pengguna dan klien.
   • Tetapkan masa berlaku kode menjadi sekitar 10 menit.

4. Alihkan kembali ke Google:

   • Alihkan browser ke URL yang diberikan di redirect_uri.
   • Tambahkan parameter kueri berikut:
     • code: Kode otorisasi yang Anda buat.
     • state: Nilai status yang tidak diubah yang diterima dari Google.

Langkah 2: Menangani permintaan pertukaran token

Endpoint pertukaran token Anda memproses dua jenis permintaan: menukar kode dengan token, dan memperbarui token akses yang masa berlakunya telah berakhir. Untuk mengetahui detail kontrak protokol dan persyaratan parameter, lihat Endpoint Pertukaran Token.

A. Menukar kode otorisasi dengan token

Saat menerima kode otorisasi, Google akan memanggil endpoint pertukaran token Anda (POST) untuk mengambil token.

1. Validasi permintaan:

   • Verifikasi client_id dan client_secret.
   • Pastikan kode otorisasi valid dan masa berlakunya belum berakhir.
   • Pastikan redirect_uri cocok dengan nilai yang digunakan di Langkah 1.
   • Jika validasi gagal, tampilkan HTTP 400 Bad Request dengan {"error": "invalid_grant"}.

2. Terbitkan token:

   • Buat refresh_token berumur panjang dan access_token berumur pendek (biasanya 1 jam).
   • Tampilkan 200 OK HTTP dengan respons token JSON standar.

B. Memperbarui token akses

Saat masa berlaku token akses berakhir, Google akan meminta token baru menggunakan token refresh.

1. Validasi permintaan:

   • Verifikasi client_id, client_secret, dan refresh_token.
   • Jika validasi gagal, tampilkan HTTP 400 Bad Request dengan {"error": "invalid_grant"}.

2. Terbitkan token akses baru:

   • Buat access_token berumur pendek baru.
   • Tampilkan 200 OK HTTP dengan respons token JSON (secara opsional menyertakan token refresh baru).

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:

• Linked Account Sign-In with Google One Tap.
• Frictionless subscription on AndroidTV.

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.

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.

Memvalidasi implementasi

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration settings to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.