Bermigrasi dari Login dengan Google

Panduan ini membantu Anda memahami perubahan dan langkah yang diperlukan untuk berhasil memigrasikan library JavaScript dari library platform Login dengan Google sebelumnya ke library Layanan Identitas Google yang lebih baru untuk autentikasi.

Jika klien Anda menggunakan Library Klien Google API untuk JavaScript atau library sebelumnya lainnya untuk otorisasi, lihat Bermigrasi ke Layanan Identitas Google untuk mengetahui informasi selengkapnya.

Autentikasi dan otorisasi

Autentikasi menetapkan siapa seseorang, dan biasanya disebut sebagai pendaftaran atau login pengguna. Otorisasi adalah proses untuk memberikan atau menolak akses ke data atau resource. Misalnya, aplikasi Anda meminta persetujuan pengguna untuk mengakses Google Drive pengguna.

Seperti library platform Login dengan Google sebelumnya, library Google Identity Services yang baru dibuat untuk mendukung proses autentikasi dan otorisasi.

Namun, library yang lebih baru memisahkan kedua proses untuk mengurangi kerumitan bagi developer untuk mengintegrasikan Akun Google dengan aplikasi Anda.

Jika kasus penggunaan Anda hanya menyangkut autentikasi, lanjutkan membaca halaman ini.

Jika kasus penggunaan Anda mencakup otorisasi, baca Cara kerja otorisasi pengguna dan Bermigrasi ke Google Identity Services untuk memastikan aplikasi Anda menggunakan API baru yang ditingkatkan.

Beberapa hal yang berubah

Untuk pengguna, library Layanan Identitas Google baru menawarkan berbagai peningkatan kegunaan. Sorotan meliputi:

• Alur fitur Sekali Ketuk yang rendah dan Login otomatis dengan lebih sedikit langkah individual,
• tombol {i>login<i} yang baru dengan personalisasi pengguna,
• branding yang konsisten dan perilaku login yang seragam di seluruh web meningkatkan pemahaman dan kepercayaan,
• membuka konten dengan cepat; pengguna dapat langsung mendaftar dan login dari mana saja di situs Anda, tanpa terlebih dahulu mengunjungi halaman login atau akun.

Bagi developer, fokus kami adalah mengurangi kompleksitas, meningkatkan keamanan, dan mempercepat integrasi Anda secepat mungkin. Beberapa peningkatan ini mencakup:

• Opsi untuk menambahkan login pengguna ke konten statis situs Anda hanya dengan HTML,
• pemisahan autentikasi login dari otorisasi dan pembagian data pengguna, kompleksitas integrasi OAuth 2.0 tidak lagi diperlukan untuk memproses login pengguna ke situs Anda.
• mode pop-up dan pengalihan akan tetap didukung, tetapi infrastruktur OAuth 2.0 Google kini mengalihkan ke endpoint login server backend Anda.
• konsolidasi kemampuan dari kedua library JavaScript Google Identity dan Google API sebelumnya ke dalam satu library baru,
• untuk respons login, sekarang Anda bisa memutuskan apakah akan menggunakan Promise dan pengalihan melalui fungsi gaya pengambil telah dihapus agar lebih praktis.

Contoh migrasi login

Jika Anda bermigrasi dari tombol Login dengan Google yang sudah ada dan hanya tertarik untuk memproses login pengguna ke situs Anda, perubahan yang paling mudah adalah mengupdate ke tombol baru yang dipersonalisasi. Hal ini dapat dilakukan dengan menukar library JavaScript dan mengupdate codebase untuk menggunakan objek login baru.

Library dan konfigurasi

Library platform Login dengan Google sebelumnya: apis.google.com/js/platform.js, dan library klien Google API untuk JavaScript: gapi.client tidak lagi diperlukan untuk autentikasi dan otorisasi pengguna. Library tersebut telah diganti dengan satu library JavaScript Google Identity Services baru: accounts.google.com/gsi/client.

Tiga modul JavaScript sebelumnya: api, client, dan platform yang digunakan untuk login, semuanya dimuat dari apis.google.com. Untuk membantu mengidentifikasi lokasi tempat library sebelumnya dapat disertakan dalam situs Anda, biasanya:

• tombol login default memuat apis.google.com/js/platform.js,
• grafik tombol kustom memuat apis.google.com/js/api:client.js, dan
• penggunaan langsung gapi.client memuat apis.google.com/js/api.js.

Pada umumnya, Anda dapat terus menggunakan kredensial Client ID aplikasi web yang sudah ada. Sebagai bagian dari migrasi Anda, sebaiknya tinjau Kebijakan OAuth 2.0 kami dan gunakan Konsol API Google untuk mengonfirmasi, dan jika perlu, memperbarui setelan klien berikut:

• aplikasi pengujian dan produksi menggunakan Project terpisah dan memiliki Client ID sendiri,
• Jenis Client ID OAuth 2.0 adalah "Aplikasi web", dan
• HTTPS digunakan untuk asal JavaScript yang diotorisasi dan URI pengalihan.

Mengidentifikasi kode dan pengujian yang terpengaruh

Cookie debug dapat membantu menemukan kode yang terpengaruh dan menguji perilaku setelah penghentian.

Dalam aplikasi besar atau kompleks, mungkin sulit untuk menemukan semua kode yang terpengaruh oleh penghentian modul gapi.auth2. Untuk mencatat penggunaan yang sudah ada yang akan segera tidak digunakan lagi ke konsol, tetapkan nilai cookie G_AUTH2_MIGRATION ke informational. Secara opsional, tambahkan titik dua yang diikuti dengan nilai kunci untuk mencatat log ke penyimpanan sesi juga. Setelah login dan menerima kredensial, tinjau atau kirim log yang dikumpulkan ke backend untuk dianalisis di lain waktu. Misalnya, informational:showauth2use menyimpan origin dan URL ke kunci penyimpanan sesi yang bernama showauth2use.

Untuk memverifikasi perilaku aplikasi saat modul gapi.auth2 tidak lagi dimuat, tetapkan nilai cookie G_AUTH2_MIGRATION ke enforced. Hal ini memungkinkan pengujian perilaku pasca-penghentian sebelum tanggal penerapan.

Kemungkinan nilai cookie G_AUTH2_MIGRATION:

• enforced Jangan muat modul gapi.auth2.
• informational Catat penggunaan kemampuan yang tidak digunakan lagi ke konsol JS. Juga mencatat ke penyimpanan sesi saat nama kunci opsional ditetapkan: informational:key-name.

Untuk meminimalkan dampak terhadap pengguna, sebaiknya Anda menetapkan cookie ini terlebih dahulu secara lokal selama pengembangan dan pengujian, sebelum menggunakannya di lingkungan produksi.

HTML dan JavaScript

Dalam skenario login khusus autentikasi ini, kode contoh dan rendering tombol Login dengan Google yang sudah ada akan ditampilkan. Pilih mode Pop-up atau Pengalihan untuk melihat perbedaan pada cara penanganan respons autentikasi oleh callback JavaScript atau pengalihan aman ke endpoint login server backend Anda.

Cara sebelumnya

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

Cara baru

Untuk menggunakan library baru dalam skenario login khusus autentikasi, pilih dari mode Pop-up atau Pengalihan dan gunakan contoh kode untuk mengganti penerapan yang ada di halaman login Anda.

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

Dalam contoh khusus autentikasi ini, library accounts.google.com/gsi/client, class g_id_signin, dan objek g_id_onload baru menggantikan library apis.google.com/js/platform.js dan objek g-signin2 sebelumnya.

Selain merender tombol baru yang dipersonalisasi, kode contoh juga menampilkan pop-up Sekali Ketuk yang baru. Di mana pun Anda menampilkan tombol yang dipersonalisasi, sebaiknya tampilkan juga pop-up Sekali Ketuk untuk meminimalkan friksi pengguna selama proses pendaftaran dan login.

Meskipun tidak direkomendasikan karena adanya peningkatan friksi login, tombol baru yang dipersonalisasi dapat ditampilkan sendiri, tanpa menampilkan dialog Sekali Ketuk secara bersamaan. Untuk melakukannya, tetapkan atribut data-auto_prompt ke false.

API HTML dan JavaScript

Contoh sebelumnya menunjukkan cara menggunakan HTML API baru untuk menambahkan login ke situs Anda. Atau, Anda dapat menggunakan JavaScript API yang setara secara fungsional, atau memadupadankan API HTML dan JavaScript di seluruh situs Anda.

Untuk melihat opsi penyesuaian tombol secara interaktif seperti jenis callback dan atribut seperti: warna, ukuran, bentuk, teks, dan tema, lihat Pembuat kode kami. Alat ini dapat digunakan untuk membandingkan berbagai opsi dengan cepat dan membuat cuplikan HTML untuk digunakan di situs Anda.

Login dari halaman mana pun dengan Sekali Ketuk

Sekali Ketuk adalah cara baru yang memudahkan pengguna untuk mendaftar atau login ke situs Anda. Dengan metode ini, Anda dapat mengaktifkan login pengguna secara langsung dari halaman mana pun di situs Anda dan menghilangkan keharusan pengguna untuk mengunjungi halaman login khusus. Dengan kata lain, hal ini akan mengurangi hambatan pendaftaran dan login dengan memberikan fleksibilitas kepada pengguna untuk melakukan pendaftaran dan login dari halaman selain halaman login Anda.

Untuk mengaktifkan login dari halaman mana pun, sebaiknya sertakan g_id_onload di header, footer, atau objek lain yang disertakan di seluruh situs Anda.

Sebaiknya tambahkan juga g_id_signin, yang menampilkan tombol login yang dipersonalisasi, hanya pada halaman login atau pengelolaan akun pengguna Anda. Beri pengguna pilihan untuk mendaftar atau login dengan menampilkan tombol bersama tombol penyedia identitas gabungan lainnya serta kolom entri nama pengguna dan sandi.

Respons token

Login pengguna tidak lagi mengharuskan Anda memahami atau menggunakan kode otorisasi OAuth 2.0, token akses, atau token refresh. Sebagai gantinya, Token ID Token Web JSON (JWT) digunakan untuk berbagi status login dan profil pengguna. Untuk penyederhanaan lebih lanjut, Anda tidak lagi perlu menggunakan metode pengakses gaya "pengambil" untuk menangani data profil pengguna.

Kredensial token ID JWT yang ditandatangani Google dan aman ditampilkan:

• ke pengendali callback JavaScript berbasis browser pengguna dalam mode Pop-up, atau
• ke server backend Anda melalui pengalihan Google ke endpoint login Anda saat tombol Login dengan Google ux_mode disetel ke redirect.

Dalam kedua kasus tersebut, perbarui pengendali callback yang ada dengan menghapus:

• panggilan ke googleUser.getBasicProfile(),
• referensi ke BasicProfile, dan panggilan terkait ke metode getId(), getName(), getGivenName(), getFamilyName(), getImageUrl(), getEmail(), dan
• penggunaan objek AuthResponse.

Sebagai gantinya, gunakan referensi langsung ke sub-kolom credential di objek CredentialResponse JWT baru untuk menangani data profil pengguna.

Selain itu, dan khusus untuk mode Pengalihan, pastikan untuk mencegah Pemalsuan Permintaan Lintas Situs (CSRF) dan Verifikasi token ID Google di server backend.

Untuk lebih memahami cara pengguna berinteraksi dengan situs Anda, kolom select_by di CredentialResponse dapat digunakan untuk menentukan hasil izin pengguna dan alur login spesifik yang digunakan.

Izin pengguna dan mencabut izin

Saat pengguna login pertama kali ke situs Anda, Google akan meminta izin kepada pengguna untuk membagikan profil akunnya ke aplikasi Anda. Profil pengguna hanya akan dibagikan ke aplikasi Anda setelah memberikan izin dalam payload kredensial token ID. Mencabut akses ke profil ini sama dengan mencabut token akses di library login sebelumnya.

Pengguna dapat mencabut izin dan memutuskan koneksi aplikasi Anda dari Akun Google mereka dengan membuka https://myaccount.google.com/permissions. Atau, metode tersebut dapat terputus langsung dari aplikasi Anda dengan memicu panggilan API yang Anda terapkan; metode disconnect sebelumnya telah diganti oleh metode revoke yang lebih baru.

Saat pengguna menghapus akunnya di platform Anda, praktik terbaiknya adalah menggunakan revoke untuk memutuskan koneksi aplikasi Anda dari Akun Google mereka.

Sebelumnya, auth2.signOut() dapat digunakan untuk membantu mengelola logout pengguna dari aplikasi Anda. Setiap penggunaan auth2.signOut() harus dihapus, dan aplikasi Anda harus langsung mengelola status sesi dan status login per pengguna.

Status sesi dan Pemroses

Library baru tidak mempertahankan status login atau status sesi untuk aplikasi web Anda.

Status login Akun Google, serta status sesi dan status login aplikasi Anda adalah konsep yang berbeda dan terpisah.

Status login pengguna ke Akun Google mereka dan aplikasi Anda tidak saling bergantung, kecuali selama momen login itu sendiri, jika Anda mengetahui bahwa pengguna telah berhasil mengautentikasi dan login ke Akun Google-nya.

Jika Login dengan Google, Sekali Ketuk, atau Login Otomatis disertakan di pengguna situs, pengguna harus login terlebih dahulu ke Akun Google mereka untuk:

• memberikan izin untuk membagikan profil pengguna mereka saat pertama kali mendaftar atau masuk ke situs Anda,
• dan kemudian untuk login saat kunjungan kembali ke situs Anda.

Pengguna dapat tetap login, logout, atau beralih ke Akun Google lain saat mempertahankan sesi login aktif di situs Anda.

Anda sekarang bertanggung jawab untuk mengelola secara langsung status login bagi pengguna aplikasi web Anda. Sebelumnya, Login dengan Google membantu Memantau status sesi pengguna.

Hapus semua referensi ke auth2.attachClickHandler() dan pengendali callback terdaftarnya.

Sebelumnya, Pemroses digunakan untuk membagikan perubahan status login untuk Akun Google pengguna. Pemroses tidak lagi didukung.

Hapus semua referensi ke listen(), auth2.currentUser, dan auth2.isSignedIn.

Kukis

Login dengan Google membatasi penggunaan cookie, berikut deskripsi cookie ini. Lihat Cara Google menggunakan cookie untuk informasi selengkapnya tentang jenis cookie lain yang digunakan oleh Google.

Cookie G_ENABLED_IDPS yang ditetapkan oleh Library Google Sign-in Platform sebelumnya tidak digunakan lagi.

Library Google Identity Services yang baru dapat secara opsional menetapkan cookie lintas-domain ini berdasarkan opsi konfigurasi Anda:

• g_state menyimpan status logout pengguna dan disetel saat menggunakan pop-up Sekali Ketuk atau Login otomatis,

• g_csrf_token adalah cookie pengiriman ganda yang digunakan untuk mencegah serangan CSRF dan ditetapkan saat endpoint login Anda dipanggil. Nilai untuk URI login Anda dapat ditetapkan secara eksplisit atau dapat ditetapkan secara default ke URI halaman saat ini. Endpoint login Anda dapat dipanggil dalam kondisi berikut saat menggunakan:

  • HTML API dengan data-ux_mode=redirect atau saat data-login_uri disetel, atau

  • JavaScript API dengan ux_mode=redirect dan yang google.accounts.id.prompt() tidak digunakan untuk menampilkan Login Sekali Ketuk atau Login otomatis.

Jika Anda memiliki layanan yang mengelola cookie, pastikan untuk menambahkan dua cookie baru dan menghapus cookie sebelumnya saat migrasi selesai.

Jika Anda mengelola beberapa domain atau subdomain, lihat Menampilkan Sekali Ketuk di seluruh Subdomain untuk petunjuk lebih lanjut cara menggunakan cookie g_state.

Referensi migrasi objek untuk login pengguna