Bermigrasi dari Login dengan Google

Panduan ini membantu Anda memahami perubahan dan langkah-langkah yang diperlukan untuk berhasil memigrasikan library JavaScript dari library platform Login Google sebelumnya ke library Google Identity Services 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 menentukan identitas seseorang, dan biasanya disebut sebagai pendaftaran atau login pengguna. Otorisasi adalah proses pemberian atau penolakan akses ke data atau resource. Misalnya, aplikasi Anda meminta izin pengguna untuk mengakses Google Drive pengguna.

Seperti library platform Google Sign-In sebelumnya, library Google Identity Services baru dibuat untuk mendukung proses autentikasi dan otorisasi.

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

Jika kasus penggunaan Anda hanya terkait dengan 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.

Yang berubah

Bagi pengguna, library Google Identity Services baru menawarkan banyak peningkatan kegunaan. Sorotannya meliputi:

• Alur login Sekali Ketuk dan Otomatis baru yang lebih lancar dengan lebih sedikit langkah individual,
• tombol login yang diperbarui dengan personalisasi pengguna,
• branding yang konsisten, dan perilaku login yang seragam di seluruh web meningkatkan pemahaman dan kepercayaan,
• mengakses konten dengan cepat; pengguna dapat langsung mendaftar dan login dari mana saja di situs Anda tanpa harus membuka halaman login atau akun terlebih dahulu.

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

• Opsi untuk menambahkan login pengguna ke konten statis situs 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 terus didukung, tetapi infrastruktur OAuth 2.0 Google kini mengalihkan ke endpoint login server backend Anda,
• penggabungan kemampuan dari library JavaScript Google Identity dan Google API sebelumnya menjadi satu library baru,
• untuk respons login, kini Anda dapat 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 ada dan hanya ingin membuat pengguna login ke situs Anda, perubahan yang paling mudah adalah memperbarui ke tombol yang dipersonalisasi baru. Hal ini dapat dilakukan dengan menukar library JavaScript dan mengupdate codebase Anda untuk menggunakan objek login baru.

Library dan konfigurasi

Library platform Google Login 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 Anda mengidentifikasi lokasi tempat library sebelumnya mungkin disertakan di situs Anda, biasanya:

• tombol login default memuat apis.google.com/js/platform.js,
• grafis 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 ada. Sebagai bagian dari migrasi, sebaiknya tinjau Kebijakan OAuth 2.0 kami dan gunakan Konsol API Google untuk mengonfirmasi, dan jika perlu, perbarui setelan klien berikut:

• aplikasi pengujian dan produksi Anda 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 yang terpengaruh dan mengujinya

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

Dalam aplikasi yang besar atau kompleks, mungkin akan sulit untuk menemukan semua kode yang terpengaruh oleh penghentian modul gapi.auth2. Untuk mencatat penggunaan kemampuan yang akan segera tidak digunakan lagi ke konsol ke dalam log, tetapkan nilai cookie G_AUTH2_MIGRATION ke informational. Jika ingin, tambahkan titik dua, diikuti dengan nilai kunci untuk juga mencatat ke penyimpanan sesi. Setelah login dan menerima kredensial, tinjau atau kirim log yang dikumpulkan ke backend untuk dianalisis nanti. Misalnya, informational:showauth2use menyimpan origin dan URL ke kunci penyimpanan sesi 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 pascapenghentian sebelum tanggal penerapan.

Kemungkinan nilai cookie G_AUTH2_MIGRATION:

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

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

HTML dan JavaScript

Dalam skenario login khusus autentikasi ini, contoh kode dan rendering tombol Login dengan Google yang ada akan ditampilkan. Pilih dari mode Pop-up atau Pengalihan untuk melihat perbedaan cara penanganan respons autentikasi oleh callback JavaScript atau dengan 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 Popup atau Redirect 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 pendaftaran dan login.

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

HTML dan JavaScript API

Contoh sebelumnya menunjukkan cara menggunakan HTML API baru untuk menambahkan login ke situs Anda. Atau, Anda dapat menggunakan JavaScript API yang setara secara fungsi, 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 mudah bagi pengguna untuk mendaftar atau login ke situs Anda. Dengan fitur ini, Anda dapat mengaktifkan login pengguna langsung dari halaman mana pun di situs Anda dan menghilangkan kebutuhan pengguna untuk mengunjungi halaman login khusus. Dengan kata lain, hal ini mengurangi hambatan pendaftaran dan login dengan memberi pengguna fleksibilitas untuk mendaftar dan login dari halaman selain halaman login Anda.

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

Sebaiknya tambahkan juga g_id_signin, yang menampilkan tombol login yang dipersonalisasi, hanya di halaman login atau pengelolaan akun pengguna Anda. Berikan pilihan pendaftaran atau login kepada pengguna dengan menampilkan tombol di samping 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, token akses, atau token refresh OAuth 2.0. Sebagai gantinya, Token ID Token Web JSON (JWT) digunakan untuk membagikan status login dan profil pengguna. Sebagai penyederhanaan lebih lanjut, Anda tidak lagi diwajibkan untuk menggunakan metode akses gaya "pengambil" untuk menggunakan data profil pengguna.

Kredensial token ID JWT yang aman dan ditandatangani Google ditampilkan:

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

Dalam kedua kasus, 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 dalam objek CredentialResponse JWT baru untuk menggunakan data profil pengguna.

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

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

Izin pengguna dan pencabutan izin

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

Pengguna dapat mencabut izin dan memutuskan hubungan aplikasi dari Akun Google mereka dengan membuka https://myaccount.google.com/permissions. Atau, keduanya dapat terputus langsung dari aplikasi Anda dengan memicu panggilan API yang Anda implementasikan; metode disconnect sebelumnya telah diganti dengan 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-nya.

Sebelumnya, auth2.signOut() dapat digunakan untuk membantu mengelola logout pengguna dari aplikasi Anda. Semua 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 tergantung, kecuali selama momen login itu sendiri saat Anda mengetahui bahwa pengguna telah berhasil diautentikasi dan login ke Akun Google mereka.

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

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

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

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

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

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 menggunakan cookie secara terbatas, berikut penjelasan cookie tersebut. Lihat Cara Google menggunakan cookie untuk mengetahui informasi selengkapnya tentang jenis cookie lain yang digunakan oleh Google.

Cookie G_ENABLED_IDPS yang ditetapkan oleh Library Platform Login dengan Google versi sebelumnya tidak lagi digunakan.

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

• g_state menyimpan status logout pengguna dan ditetapkan 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 ini saat menggunakan:

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

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

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

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

Referensi migrasi objek untuk login pengguna