Menggunakan Model Kode

Library Layanan Identitas Google memungkinkan pengguna meminta kode otorisasi dari Google menggunakan alur Popup atau Pengalihan UX berbasis browser. Tindakan ini akan 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 akan meminta kode otorisasi dari Google.
• Google akan merespons, dengan mengirimkan kode otorisasi unik ke callback di aplikasi web JavaScript 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 tersebut. Setelah divalidasi, kode ini ditukar dengan token refresh per pengguna dan token refresh menggunakan permintaan ke endpoint token Google.
• Google memvalidasi kode otorisasi, mengonfirmasi permintaan yang berasal dari platform aman Anda, menerbitkan akses dan token refresh, serta menampilkan token dengan memanggil endpoint login yang dihosting oleh platform Anda.
• Endpoint login Anda menerima token akses dan refresh, yang menyimpan token refresh dengan aman untuk digunakan nanti.

Menginisialisasi Code Client

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

Mode pop-up atau Pengalihan

Anda dapat memilih untuk membagikan kode autentikasi 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, yang 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 mengharuskan pengunjung 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. Nilai harus sama persis dengan salah satu URI pengalihan yang diberi otorisasi untuk klien OAuth 2.0 yang Anda konfigurasikan di Konsol API. URL tersebut juga harus sesuai dengan aturan validasi URI Pengalihan kami.

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

Mencegah serangan CSRF

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

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

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"
});

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 pengguna:

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

Tindakan ini akan mengharuskan pengguna untuk login ke Akun Google dan memberikan izin untuk membagikan setiap cakupan sebelum menampilkan kode otorisasi ke endpoint pengalihan atau pengendali callback 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, menyampaikan 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 dalam parameter kode URL. Untuk menerima kode otorisasi:

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

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

Endpoint otorisasi

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

Contoh permintaan GET dengan parameter URL ke endpoint yang 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

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

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

Mendapatkan token akses dan refresh

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

Ikuti petunjuk mulai dari Langkah 5: Kode otorisasi Exchange untuk token refresh dan akses dalam panduan Menggunakan OAuth 2.0 untuk Aplikasi Server Web.

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 Perlindungan Lintas Akun.

Biasanya, platform backend Anda akan memanggil Google API menggunakan token akses. Jika aplikasi web Anda juga akan langsung memanggil Google API dari browser pengguna, Anda harus mengimplementasikan cara untuk berbagi token akses dengan aplikasi web, hal tersebut 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 mengaktifkan library untuk memanggil Google API.