Account Linking API Anda

Halaman referensi ini mendokumentasikan endpoint API yang harus diterapkan layanan Anda untuk mendukung Penautan Akun dengan Google. Hal ini mencakup Penautan Akun berbasis OAuth, Penautan Akun yang Sederhana, dan Pengalihan Aplikasi.

Prasyarat dan standar

Agar berhasil menerapkan endpoint ini, layanan Anda harus mematuhi standar berikut:

  • OAuth 2.0: Sesuai dengan RFC 6749.
  • Pencabutan Token: Sesuai dengan RFC 7009.
  • JSON Web Tokens (JWT): Sesuai dengan RFC 7519 (diperlukan untuk Penautan yang Disederhanakan).
  • HTTPS: Semua endpoint harus ditayangkan melalui koneksi HTTPS yang aman.

Endpoint Otorisasi

Endpoint otorisasi bertanggung jawab untuk mengautentikasi pengguna dan mendapatkan persetujuan mereka untuk menautkan akun mereka dengan Google.

  • URL: Dikonfigurasi di Konsol Actions atau Konsol Google Cloud.
  • Metode: GET

Parameter Permintaan

Parameter Deskripsi
client_id ID klien yang Anda tetapkan untuk Google.
redirect_uri URL tempat Anda mengirim respons terhadap permintaan ini.
state Nilai pembukuan yang dikirim kembali ke Google tanpa perubahan di URI pengalihan.
response_type Harus berupa code untuk alur kode otorisasi.
scope (Opsional) Daftar cakupan yang dipisahkan spasi untuk data yang diminta Google.
user_locale (Opsional) Setelan bahasa Akun Google, yang ditentukan menggunakan tag bahasa BCP-47 (misalnya, en-US).

Endpoint Pertukaran Token

Endpoint ini bertanggung jawab untuk menukar kode otorisasi dengan token dan memperbarui token akses yang sudah tidak berlaku.

  • URL: Dikonfigurasi di Konsol Actions atau Konsol Google Cloud.
  • Metode: POST
  • Content-Type: application/x-www-form-urlencoded

Menukarkan Kode Otorisasi dengan Token

Parameter berikut digunakan dalam permintaan pertukaran token awal.

Parameter Permintaan

Parameter Deskripsi
client_id ID klien yang Anda tetapkan untuk Google.
client_secret Rahasia klien yang Anda tetapkan ke Google.
grant_type Harus berupa authorization_code.
code Kode otorisasi yang diterima dari endpoint otorisasi.
redirect_uri URI pengalihan yang sama dengan yang digunakan dalam permintaan awal.

Menukar Token Refresh dengan Token Akses

Parameter berikut digunakan saat memperbarui token akses.

Parameter Permintaan

Parameter Deskripsi
client_id ID klien yang Anda tetapkan untuk Google.
client_secret Rahasia klien yang Anda tetapkan ke Google.
grant_type Harus berupa refresh_token.
refresh_token Token refresh yang sebelumnya dikeluarkan untuk Google.

Respons (JSON)

Menampilkan respons yang berhasil dengan objek JSON dalam isi respons HTTPS.

  • Status HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8
Kolom Deskripsi
token_type Wajib. Harus berupa bearer.
access_token Wajib. Token jangka pendek yang digunakan untuk mengakses API layanan Anda.
refresh_token Wajib untuk authorization_code grant_type. Token yang berlaku lama yang digunakan untuk mendapatkan token akses baru.
expires_in Wajib. Masa berlaku token akses yang tersisa dalam hitungan detik.

Respons Error

Jika permintaan ke endpoint token gagal, tampilkan error HTTP 400 Bad Request beserta respons JSON yang berisi kolom berikut:

  • Status HTTP: 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
Kolom error (JSON) Deskripsi
error Wajib. Harus berupa invalid_grant.
error_description (Opsional) Teks yang dapat dibaca oleh manusia yang memberikan informasi tambahan.

Menangani Intent Penautan yang Sederhana

Jika layanan Anda mendukung Penautan Akun yang Disederhanakan (OAuth dengan Login dengan Google), endpoint pertukaran token Anda juga harus mendukung pernyataan Token Web JSON (JWT) dan menerapkan maksud check, create, dan get.

Parameter berikut digunakan dalam permintaan ini:

Parameter Permintaan

Parameter Deskripsi
intent Intent penautan yang disederhanakan tertentu yang diminta: check, get, atau create.
grant_type Untuk permintaan ini, parameter ini selalu memiliki nilai urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion Token Web JSON (JWT) yang memberikan pernyataan bertanda tangan tentang identitas pengguna Google. JWT berisi informasi yang mencakup ID Akun Google, nama, dan alamat email pengguna.

Server Anda harus memvalidasi JWT ini menggunakan kriteria yang tercantum di bagian Validasi JWT.
client_id ID klien yang Anda tetapkan untuk Google.
client_secret Rahasia klien yang Anda tetapkan ke Google.
scope Opsional: Cakupan apa pun yang telah Anda konfigurasi agar Google meminta dari pengguna. Biasanya ada selama maksud get dan create.
response_type Wajib untuk maksud create: Harus ditetapkan ke token.

Validasi JWT

Untuk memastikan keamanan penautan yang disederhanakan, server Anda harus memvalidasi assertion (JWT) menggunakan kriteria berikut:

  • Tanda tangan: Verifikasi tanda tangan terhadap kunci publik Google (tersedia di endpoint JWK Google).
  • Penerbit (iss): Harus https://accounts.google.com.
  • Audiens (aud): Harus cocok dengan ID Klien Google API yang ditetapkan ke integrasi Anda.
  • Masa berlaku (exp): Harus di masa mendatang.

Respons untuk maksud check

Permintaan dengan intent=check memverifikasi apakah Akun Google (yang diidentifikasi oleh klaim sub atau email dalam pernyataan JWT yang didekode) ada di database pengguna Anda.

  • Status HTTP: 200 OK (Akun ditemukan) atau 404 Not Found (Akun tidak ditemukan)
  • Content-Type: application/json;charset=UTF-8
Kolom Deskripsi
account_found Wajib. true jika akun ada, false jika tidak.

Respons untuk maksud get

Permintaan dengan intent=get meminta token akses untuk Akun Google yang ada.

  • Status HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

Objek JSON respons yang berhasil menggunakan struktur yang sama persis dengan respons Pertukaran Token standar yang berhasil (menampilkan access_token, refresh_token, dll.).

Jika akun tidak dapat ditautkan, error HTTP 401 akan ditampilkan.

  • Status HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Kolom error (JSON) Deskripsi
error Wajib. Harus berupa linking_error.
login_hint (Opsional) Alamat email pengguna yang akan diteruskan ke alur penautan OAuth penggantian.

Respons untuk maksud create

Permintaan dengan intent=create meminta pembuatan akun pengguna baru dengan informasi yang diberikan dalam JWT.

  • Status HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

Objek JSON respons yang berhasil menggunakan struktur yang sama persis dengan respons Pertukaran Token standar yang berhasil (menampilkan access_token, refresh_token, dll.).

Jika pengguna sudah ada, error HTTP 401 akan ditampilkan untuk meminta pengguna menautkan akun yang sudah ada.

  • Status HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Kolom error (JSON) Deskripsi
error Wajib. Harus berupa linking_error.
login_hint Alamat email pengguna yang akan diteruskan ke alur penautan OAuth penggantian.

Endpoint UserInfo (Opsional)

Digunakan untuk mengambil informasi profil dasar tentang pengguna tertaut, seperti yang ditentukan dalam spesifikasi OpenID Connect Core 1.0. Tindakan ini diperlukan untuk fitur seperti "Penautan yang Disederhanakan" atau "Login Sekali Ketuk".

  • Metode: GET
  • Autentikasi: Authorization: Bearer ACCESS_TOKEN

Respons (JSON)

Menampilkan respons yang berhasil dengan objek JSON dalam isi respons HTTPS.

  • Status HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

Kolom Respons

Kolom Deskripsi
sub Wajib. ID unik yang mengidentifikasi pengguna di sistem Anda.
email Wajib. Alamat email pengguna.
email_verified Wajib. Boolean yang menunjukkan apakah alamat email telah diverifikasi.
given_name (Opsional) Nama depan pengguna.
family_name (Opsional) Nama belakang pengguna.
name (Opsional) Nama lengkap pengguna.
picture (Opsional) URL ke foto profil pengguna.

Respons Error

Jika masa berlaku token akses tidak valid atau telah berakhir, tampilkan error HTTP 401 Tidak Sah. Anda juga harus menyertakan header respons WWW-Authenticate.

Setiap respons yang tidak berhasil (4xx atau 5xx) yang ditampilkan selama proses penautan dianggap tidak dapat dipulihkan. Dalam kasus ini, Google akan menghapus semua token yang diambil, dan pengguna harus memulai proses penautan akun lagi.

Endpoint Pencabutan Token (Opsional)

Mengizinkan Google memberi tahu layanan Anda saat pengguna membatalkan tautan akunnya dari platform Google. Endpoint ini harus memenuhi persyaratan yang dijelaskan dalam RFC 7009.

  • Metode: POST
  • Content-Type: application/x-www-form-urlencoded

Parameter Permintaan

Parameter Deskripsi
client_id String yang mengidentifikasi asal permintaan sebagai Google. String ini harus didaftarkan dalam sistem Anda sebagai ID unik Google.
client_secret String rahasia yang Anda daftarkan ke Google untuk layanan Anda.
token Token yang akan dicabut.
token_type_hint (Opsional) Petunjuk tentang jenis token yang dicabut, baik access_token maupun refresh_token. Jika tidak ditentukan, setelan defaultnya adalah access_token.

Respons

Menampilkan respons yang berhasil saat token berhasil dihapus, atau jika token sudah tidak valid.

  • Status HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

Respons Error

Jika token tidak dapat dihapus karena alasan apa pun (misalnya, database tidak tersedia), tampilkan error HTTP 503. Google akan mencoba lagi permintaan nanti atau seperti yang ditentukan oleh header Retry-After.

  • Status HTTP: 503 Service Unavailable
  • Content-Type: application/json;charset=UTF-8
  • Header: Retry-After: <HTTP-date / delay-seconds>