Google Account Linking API

Halaman referensi ini mendokumentasikan endpoint dan antarmuka yang ditawarkan Google yang digunakan aplikasi Anda selama proses Penautan Akun berbasis OAuth.

Prasyarat dan standar

Agar berhasil berinteraksi dengan endpoint Google ini, integrasi Anda harus mematuhi standar berikut:

  • OAuth 2.0: Sesuai dengan RFC 6749.
  • JSON Web Tokens (JWT): Sesuai dengan RFC 7519 (untuk Penautan yang Disederhanakan dan RISC).
  • Token Peristiwa Keamanan: Sesuai dengan RFC 8417 (untuk RISC).
  • HTTPS: Semua permintaan harus dilakukan melalui koneksi HTTPS yang aman.

URI Pengalihan OAuth

Endpoint tempat layanan Anda mengalihkan browser pengguna setelah autentikasi dan izin berhasil. Parameter jalur YOUR_PROJECT_ID adalah ID yang Anda konfigurasi selama pendaftaran.

  • URL: https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

  • URL Sandbox: https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  • Metode: GET (menggunakan pengalihan browser)

Parameter Permintaan

Saat mengalihkan pengguna kembali ke Google, parameter harus ditambahkan ke URL. Bergantung pada alur OAuth yang digunakan, parameter ini diformat sebagai string kueri (alur Kode Autentikasi) atau sebagai fragmen URL (alur Implisit).

Parameter Deskripsi
code (Wajib diisi untuk Alur Kode Otorisasi) Kode otorisasi yang dihasilkan oleh layanan Anda.
state (Wajib) Nilai status yang tidak diubah yang awalnya diterima dari Google.
access_token (Wajib untuk Alur Implisit) Token akses berdurasi panjang yang dihasilkan oleh layanan Anda.
token_type (Wajib untuk Alur Implisit) Harus berupa bearer.

Respons Error

Jika permintaan ke URI pengalihan OAuth salah format, Anda akan menerima error HTTP 400 Bad Request. Isi respons akan berisi objek JSON dengan struktur berikut:

Kolom Deskripsi
sendPostBody Menentukan apakah JS harus mengalihkan ke redirectUri dengan POST. Biasanya false dalam skenario ini.
errorMessage Pesan error yang akan ditampilkan kepada klien saat pengalihan tidak dapat diselesaikan. Untuk fragmen yang tidak ada, nilainya adalah "A URI fragment or query string must be set."

Respons Error OAuth 2.0

Jika pengguna menolak memberikan izin atau layanan Anda mengalami error, layanan Anda harus mengalihkan pengguna kembali ke URI pengalihan OAuth dengan parameter error OAuth 2.0 standar (seperti error=access_denied). Google akan memproses parameter ini dan menampilkan layar error yang sesuai kepada pengguna.

RISC API (Opsional)

Digunakan oleh layanan Anda untuk secara proaktif memberi tahu Google saat pengguna membatalkan tautan akunnya di platform Anda menggunakan protokol RISC, sehingga memastikan kedua platform tetap disinkronkan.

  • URL: https://risc.googleapis.com/v1/events:publish
  • Metode: POST
  • Autentikasi: Memerlukan token Akun Layanan Google dengan izin yang sesuai.
  • Content-Type: application/json

Klaim Token Peristiwa Keamanan

Token Peristiwa Keamanan yang Anda gunakan untuk memberi tahu Google tentang peristiwa pencabutan token harus sesuai dengan persyaratan dalam tabel berikut:

Klaim Deskripsi
iss Klaim Penerbit: Ini adalah URL yang Anda hosting, dan dibagikan kepada Google selama pendaftaran.
aud Klaim Audiens: Klaim ini mengidentifikasi Google sebagai penerima JWT. Harus ditetapkan ke google_account_linking.
jti Klaim ID JWT: Ini adalah ID unik yang Anda buat untuk setiap token peristiwa keamanan.
iat Klaim Dikeluarkan Pada: Ini adalah nilai NumericDate yang merepresentasikan waktu saat token peristiwa keamanan ini dibuat.
toe Waktu Klaim Peristiwa: Ini adalah nilai NumericDate opsional yang menunjukkan waktu saat token dicabut.
exp Klaim Waktu Berakhir: Jangan sertakan kolom ini, karena peristiwa yang menghasilkan notifikasi ini telah terjadi.
events Klaim Peristiwa Keamanan: Ini adalah objek JSON, dan hanya boleh menyertakan satu peristiwa pencabutan token yang berisi kolom berikut:

  • subject_type: Ini harus ditetapkan ke oauth_token.
  • token_type: Ini adalah jenis token yang dicabut, access_token atau refresh_token.
  • token_identifier_alg: Ini adalah algoritma yang digunakan untuk mengenkode token, dan harus berupa hash_SHA512_double.
  • token: Ini adalah ID token yang dicabut.

Untuk mengetahui informasi selengkapnya tentang jenis dan format kolom, lihat JSON Web Token (JWT)

Antarmuka "Flip-Back" App Flip

Untuk Pengalihan Aplikasi, aplikasi seluler Anda harus menampilkan kode otorisasi atau token akses ke aplikasi Google.

Android (Hasil Maksud)

Aplikasi Anda dibuka menggunakan Intent. Setelah izin diberikan, proses akan selesai dan menampilkan hasil ke Google. Untuk informasi selengkapnya, lihat panduan penerapan Android.

  • Tindakan: com.google.android.gms.auth.CODE_AVAILABLE
  • Ekstra: code, state, access_token, token_type.

Aplikasi Anda membuka Google menggunakan skema URL kustom atau Universal Link HTTPS. Untuk mengetahui informasi selengkapnya, lihat panduan penerapan iOS.

  • Format: <return_url>?code=AUTHORIZATION_CODE&state=STATE_STRING