Menggunakan Model Kode

Library Google Identity Services memungkinkan pengguna meminta otorisasi kode dari Google menggunakan alur UX Pop-up atau Pengalihan berbasis browser. Ini memulai alur OAuth 2.0 yang aman dan menghasilkan token akses yang digunakan untuk memanggil Google API atas nama pengguna.

Ringkasan alur kode otorisasi OAuth 2.0:

• Dari browser, dengan gestur seperti klik tombol, Akun Google pemilik meminta kode otorisasi dari Google.
• Google merespons, mengirimkan kode otorisasi unik ke callback di aplikasi web JavaScript yang berjalan di browser pengguna, atau secara langsung memanggil endpoint kode otorisasi Anda menggunakan pengalihan browser.
• Platform backend Anda menghosting endpoint kode otorisasi dan menerima pada kode sumber. Setelah validasi, kode ini ditukarkan dengan akses per pengguna dan token refresh menggunakan permintaan ke endpoint token Google.
• Google memvalidasi kode otorisasi, mengonfirmasi bahwa permintaan berasal dari platform aman Anda, menerbitkan token akses dan refresh, dengan memanggil endpoint login yang dihosting oleh platform Anda.
• Endpoint login Anda menerima akses dan token refresh, yang menyimpan token refresh untuk digunakan di lain waktu.

Poin Penting: Di server backend, Anda menukar kode otorisasi dengan token refresh dan token akses dengan memanggil endpoint token Google.

Melakukan inisialisasi Klien Kode

Metode google.accounts.oauth2.initCodeClient() melakukan inisialisasi klien kode.

Mode pop-up atau Pengalihan

Anda dapat memilih untuk membagikan kode autentikasi menggunakan Pengalihan atau Alur penggunaan mode pop-up. Dengan mode Pengalihan, Anda menghosting otorisasi OAuth2 di server Anda dan Google mengalihkan agen pengguna ke endpoint ini, membagikan kode autentikasi sebagai parameter URL. Untuk mode Pop-up, Anda menentukan JavaScript Anda, yang mengirimkan kode otorisasi ke server Anda. Mode pop-up dapat digunakan untuk memberikan pengalaman pengguna yang lancar tanpa harus meninggalkan situs Anda.

Untuk melakukan inisialisasi klien untuk:

• Alihkan alur UX, tetapkan ux_mode ke redirect, dan nilai redirect_uri ke endpoint kode otorisasi platform Anda. Nilainya harus sama persis dengan salah satu URI pengalihan yang diberi otorisasi untuk OAuth 2.0 yang dikonfigurasi di Konsol API. Ini juga harus sesuai dengan Aturan validasi URI pengalihan.

• Alur UX pop-up, tetapkan ux_mode ke popup, dan nilai callback ke nama fungsi yang akan Anda gunakan untuk mengirim kode otorisasi ke terkelola sepenuhnya.

Poin Penting: Untuk keseimbangan terbaik antara kegunaan dan keamanan, menggunakan mode Pop-up Alur UX dengan model kode Otorisasi direkomendasikan.

Mencegah serangan CSRF

Untuk membantu mencegah serangan {i>Cross-Site-Request-Forgery<i} (CSRF) yang sedikit berbeda digunakan untuk alur UX mode Pengalihan dan Pop-up. Untuk Pengalihan mode OAuth, parameter state OAuth 2.0 akan digunakan. Lihat RFC6749 bagian 10.12 Pemalsuan Permintaan Lintas Situs untuk mengetahui informasi selengkapnya tentang cara membuat dan memvalidasi parameter state. Dengan mode Pop-up, Anda menambahkan {i>header<i} HTTP kustom ke permintaan Anda, lalu pada server Anda mengonfirmasi maka cocok dengan nilai yang diharapkan dan asal.

Pilih mode UX untuk melihat cuplikan kode yang menunjukkan kode autentikasi dan penanganan CSRF:

Mode pengalihan

Lakukan inisialisasi klien dengan Google mengalihkan browser pengguna ke file endpoint autentikasi, membagikan kode autentikasi sebagai parameter URL.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: "https://your.domain/code_callback_endpoint",
  state: "YOUR_BINDING_VALUE"
});

Mode pop-up

Lakukan inisialisasi klien tempat browser pengguna menerima kode autentikasi dari Google dan mengirimkannya ke server Anda.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', code_receiver_uri, true);
    xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    // Set custom header for CRSF
    xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
    xhr.onload = function() {
      console.log('Auth code response: ' + xhr.responseText);
    };
    xhr.send('code=' + response.code);
  },
});

Memicu Alur Kode OAuth 2.0

Panggil metode requestCode() klien kode untuk memicu alur penggunaan:

<button onclick="client.requestCode();">Authorize with Google</button>

Hal ini akan mengharuskan pengguna untuk login ke Akun Google dan setuju untuk berbagi cakupan individu sebelum mengembalikan kode otorisasi endpoint pengalihan atau handler callback.

Penanganan kode Auth

Google membuat kode otorisasi unik per pengguna yang Anda terima dan melakukan verifikasi di server backend.

Untuk mode Pop-up, pengendali yang ditentukan oleh callback, berjalan di browser, meneruskan kode otorisasi ke endpoint yang dihosting oleh platform Anda.

Untuk Mode pengalihan, permintaan GET dikirim ke endpoint yang ditentukan oleh redirect_url, yang membagikan kode otorisasi di parameter code URL. Kepada terima kode otorisasi:

• Buat endpoint Otorisasi baru jika Anda belum memiliki implementasi, atau

• Perbarui endpoint yang ada untuk menerima permintaan dan URL GET parameter. Sebelumnya, permintaan PUT dengan nilai kode otorisasi di payload digunakan.

Endpoint otorisasi

Endpoint kode otorisasi Anda harus menangani permintaan GET dengan kueri URL ini parameter string:

Nama	Nilai
{i>authuser<i}	Permintaan autentikasi login pengguna
kode	Kode otorisasi OAuth2 yang dibuat oleh Google
hd	Domain akun pengguna yang dihosting
perintah	Dialog izin pengguna
cakupan	Daftar yang dipisahkan ruang dari satu atau beberapa cakupan OAuth2 yang akan diberi otorisasi
dengan status tersembunyi akhir	Variabel status CRSF

Contoh permintaan GET dengan parameter URL ke endpoint bernama auth-code dan yang dihosting oleh example.com:

Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent

Saat alur kode otorisasi dimulai oleh library JavaScript sebelumnya, atau dengan panggilan langsung ke endpoint Google OAuth 2.0, permintaan POST akan digunakan.

Contoh permintaan POST yang berisi kode otorisasi sebagai payload dalam Isi permintaan HTTP:

Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw

Penting: Sebelumnya, POST digunakan untuk permintaan. Perbarui pengendali Anda ke terima permintaan GET dan POST atau pertimbangkan untuk menghosting dua permintaan berbeda endpoint jika Anda berencana untuk terus menggunakan library JS lama atau untuk langsung memanggil Endpoint Google OAuth 2.0 saat menggunakan library Google Identity Services.

Memvalidasi permintaan

Di server Anda, lakukan hal berikut untuk membantu menghindari serangan CSRF.

Periksa nilai parameter state, untuk mode pengalihan.

Konfirmasi bahwa header X-Requested-With: XmlHttpRequest sudah disetel untuk mode pop-up.

Selanjutnya Anda harus melanjutkan dengan mendapatkan token refresh dan mengakses dari Google hanya jika Anda berhasil memverifikasi permintaan kode auth terlebih dahulu.

Mendapatkan token akses dan refresh

Setelah platform backend Anda menerima kode otorisasi dari Google dan memverifikasi permintaan, menggunakan kode otorisasi untuk mendapatkan akses, dan menyegarkan token dari Google untuk melakukan panggilan API.

Ikuti petunjuk mulai Langkah 5: Tukarkan kode otorisasi dengan token refresh dan akses Menggunakan OAuth 2.0 untuk Server Web Panduan aplikasi.

Mengelola token

Platform Anda menyimpan token refresh dengan aman. Hapus token refresh yang disimpan saat akun pengguna dihapus, atau izin pengguna dicabut oleh google.accounts.oauth2.revoke atau langsung dari https://myaccount.google.com/permissions.

Secara opsional, Anda dapat mempertimbangkan RISC untuk melindungi akun pengguna dengan Lintas Akun Perlindungan.

Biasanya, platform backend Anda akan memanggil Google API menggunakan token akses. Jika aplikasi web Anda juga akan langsung memanggil Google API dari browser milik pengguna harus mengimplementasikan cara berbagi token akses dengan aplikasi web, melakukan sehingga berada di luar cakupan panduan ini. Saat mengikuti pendekatan ini dan menggunakan Library Klien Google API untuk JavaScript menggunakan gapi.client.SetToken() untuk menyimpan token akses di browser untuk sementara memori, dan mengaktifkan library untuk memanggil Google API.