Menggunakan Model Kode

Library Layanan Identitas Google memungkinkan pengguna meminta kode otorisasi dari Google menggunakan alur UX Pengalihan atau Pop-up berbasis browser. Hal 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 mengklik tombol, pemilik Akun Google meminta kode otorisasi dari Google.
• Google merespons dengan mengirimkan kode otorisasi unik ke callback di aplikasi web JavaScript Anda yang berjalan di browser pengguna, atau langsung memanggil endpoint kode otorisasi Anda menggunakan pengalihan browser.
• Platform backend Anda menghosting endpoint kode otorisasi dan menerima kode. Setelah divalidasi, kode ini ditukar dengan token akses dan token refresh per pengguna menggunakan permintaan ke endpoint token Google.
• Google memvalidasi kode otorisasi, mengonfirmasi bahwa permintaan berasal dari platform aman Anda, mengeluarkan token akses dan refresh, serta menampilkan token dengan memanggil endpoint login yang dihosting oleh platform Anda.
• Endpoint login Anda menerima token akses dan refresh, serta menyimpan token refresh dengan aman untuk digunakan nanti.

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

Prasyarat

Ikuti langkah-langkah yang dijelaskan di Penyiapan untuk mengonfigurasi Layar Izin OAuth, mendapatkan ID klien, dan memuat library klien.

Melakukan inisialisasi Klien Kode

Metode google.accounts.oauth2.initCodeClient() menginisialisasi klien kode.

Mode Pop-up atau Pengalihan

Anda dapat memilih untuk membagikan kode otorisasi menggunakan alur pengguna mode Pengalihan atau Pop-up. Dengan mode Pengalihan, Anda menghosting endpoint 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 pengendali callback JavaScript yang mengirimkan kode otorisasi ke server Anda. Mode pop-up dapat digunakan untuk memberikan pengalaman pengguna yang lancar tanpa pengunjung harus meninggalkan situs Anda.

Untuk menginisialisasi klien untuk:

• Alur UX pengalihan, tetapkan ux_mode ke redirect, dan nilai redirect_uri ke endpoint kode otorisasi platform Anda. Nilai harus sama persis dengan salah satu URI pengalihan yang diotorisasi untuk klien OAuth 2.0 yang Anda konfigurasi di Konsol Google Cloud. URI ini juga harus mematuhi 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 platform Anda. Nilai redirect_uri secara default adalah asal halaman yang memanggil initCodeClient. Nilai ini digunakan nanti dalam alur saat kode otorisasi ditukar dengan token akses atau refresh. Misalnya, https://www.example.com/index.html memanggil initCodeClient dan asal: https://www.example.com adalah nilai redirect_url.

Poin Penting: Untuk keseimbangan terbaik antara kegunaan dan keamanan, sebaiknya gunakan alur UX mode Pop-up dengan model Kode otorisasi.

Melindungi dari serangan CSRF

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

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

Mode pengalihan

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

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: 'https://oauth2.example.com/code',
  state: 'YOUR_BINDING_VALUE'
});

Poin Penting: Endpoint di server backend Anda menerima dan memvalidasi kode otorisasi, lalu menukarnya dengan token akses dan refresh.

Mode pop-up

Lakukan inisialisasi klien tempat pengguna memulai alur otorisasi dalam dialog pop-up. Setelah izin diberikan, kode otorisasi akan ditampilkan oleh Google ke browser pengguna menggunakan fungsi callback. Permintaan POST dari handler callback JS mengirimkan kode autentikasi ke endpoint di server backend, tempat kode tersebut diverifikasi terlebih dahulu, lalu sisa alur OAuth diselesaikan.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', "https://oauth2.example.com/code", 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);
  },
});

Poin Penting: Endpoint di server backend Anda menerima dan memvalidasi kode otorisasi, lalu menukarnya dengan token akses dan refresh.

Memicu Alur Kode OAuth 2.0

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

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

Hal ini akan mengharuskan pengguna login ke Akun Google dan memberikan izin untuk membagikan cakupan individual sebelum menampilkan kode otorisasi ke endpoint pengalihan atau pengendali panggilan balik Anda.

Penanganan kode auth

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

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

Untuk mode Pengalihan, permintaan GET dikirim ke endpoint yang ditentukan oleh redirect_uri, dengan membagikan kode otorisasi dalam parameter code URL. Untuk menerima kode otorisasi:

• Buat Authorization endpoint baru jika Anda belum memiliki penerapan yang ada, atau

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

Endpoint otorisasi

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

Nama	Nilai
authuser	Permintaan autentikasi login pengguna
kode	Kode otorisasi OAuth2 yang dibuat oleh Google
hd	Domain yang dihosting dari akun pengguna
perintah	Dialog izin pengguna
cakupan	Daftar cakupan OAuth2 yang dipisahkan spasi untuk diotorisasi
dengan status tersembunyi akhir	Variabel status CRSF

Contoh permintaan GET dengan parameter URL ke endpoint bernama auth-code dan 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 handler Anda untuk menerima permintaan GET dan POST, atau pertimbangkan untuk menghosting dua endpoint berbeda jika Anda berencana untuk terus menggunakan library JS yang lebih lama atau memanggil endpoint Google OAuth 2.0 secara langsung saat menggunakan library Layanan Identitas Google.

Validasi 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 ditetapkan untuk mode pop-up.

Kemudian, Anda harus melanjutkan dengan mendapatkan token akses dan refresh dari Google hanya jika Anda telah berhasil memverifikasi permintaan kode auth terlebih dahulu.

Mendapatkan token akses dan refresh

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

Ikuti petunjuk yang dimulai dari Langkah 5: Tukarkan kode otorisasi dengan token refresh dan akses dalam panduan Menggunakan OAuth 2.0 untuk Aplikasi Server Web.

Catatan: Saat mode pop-up digunakan, nilai redirect_uri yang digunakan pada Langkah 5 dan seterusnya adalah asal halaman yang memanggil. Misalnya, https://www.example.com/index.html memanggil initCodeClient dan asal: https://www.example.com adalah nilai redirect_url.

Mengelola token

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

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

Biasanya, platform backend Anda akan memanggil Google API menggunakan token akses. Jika aplikasi web Anda juga akan memanggil Google API secara langsung dari browser pengguna, Anda harus menerapkan cara untuk membagikan token akses dengan aplikasi web Anda. Tindakan ini berada di luar cakupan panduan ini. Saat mengikuti pendekatan ini dan menggunakan Library Klien Google API untuk JavaScript, gunakan gapi.client.SetToken() untuk menyimpan token akses sementara di memori browser, dan memungkinkan library memanggil Google API.