Bermigrasi dari Login dengan Google

Panduan ini membantu Anda memahami perubahan dan langkah-langkah yang diperlukan untuk berhasil memigrasikan library JavaScript dari Google Sign-In platform library versi sebelumnya ke Google Identity Services library versi yang lebih baru untuk autentikasi.

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

Autentikasi dan otorisasi

Autentikasi menetapkan 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 Anda untuk mengakses Google Drive pengguna.

Seperti Google Sign-In platform library sebelumnya, Google Identity Services library yang 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 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 dan yang ditingkatkan.

Yang berubah

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

• Alur Login Otomatis dan Sekali Ketuk baru yang 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.

Untuk developer, fokus kami adalah mengurangi kompleksitas, meningkatkan keamanan, dan membuat integrasi Anda secepat mungkin. Beberapa peningkatan ini meliputi:

• Opsi untuk menambahkan login pengguna ke konten statis situs Anda hanya menggunakan HTML,
• pemisahan autentikasi login dari otorisasi dan berbagi data pengguna, kompleksitas integrasi OAuth 2.0 tidak lagi diperlukan untuk membuat pengguna login ke situs Anda,
• mode pop-up dan pengalihan akan terus didukung, tetapi infrastruktur OAuth 2.0 Google kini mengalihkan ke endpoint login server backend Anda,
• penggabungan kemampuan dari kedua library JavaScript Google Identity dan Google API sebelumnya menjadi satu library baru,
• Untuk respons login, Anda kini dapat memutuskan apakah akan menggunakan Promise atau tidak, dan pengarahan tidak langsung melalui fungsi gaya getter telah dihapus untuk menyederhanakan.

Contoh migrasi login

Jika Anda melakukan migrasi dari tombol Login dengan Google yang ada dan hanya berminat untuk membuat pengguna login ke situs Anda, perubahan yang paling mudah adalah mengupdate ke tombol baru yang dipersonalisasi. Hal ini dapat dilakukan dengan menukar library JavaScript dan memperbarui codebase Anda untuk menggunakan objek login baru.

Library dan konfigurasi

Library platform Google Sign-In 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 digantikan oleh 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 dimuat apis.google.com/js/api:client.js, dan
• Penggunaan langsung gapi.client memuat apis.google.com/js/api.js.

Biasanya, 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 ID Klien sendiri,
• Jenis Client ID OAuth 2.0 adalah "Web application", 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 setelah penghentian penggunaan.

Dalam aplikasi besar atau kompleks, mungkin sulit untuk menemukan semua kode yang terpengaruh oleh penghentian penggunaan modul gapi.auth2. Untuk mencatat penggunaan kemampuan yang akan segera dihentikan ke konsol, tetapkan nilai cookie G_AUTH2_MIGRATION ke informational. Secara opsional, tambahkan titik dua yang diikuti dengan nilai kunci untuk juga mencatat ke penyimpanan sesi. Setelah login dan menerima peninjauan kredensial atau mengirim log yang dikumpulkan ke backend untuk analisis selanjutnya. Misalnya, informational:showauth2use menyimpan asal 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 setelah penghentian penggunaan sebelum tanggal pemberlakuan.

Kemungkinan nilai cookie G_AUTH2_MIGRATION:

• enforced Jangan muat modul gapi.auth2.
• informational Mencatat 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 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 ditampilkan. Pilih dari mode pop-up atau pengalihan untuk melihat perbedaan dalam cara penanganan respons autentikasi, baik oleh callback JavaScript maupun 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 pop-up atau pengalihan, lalu gunakan contoh kode untuk menggantikan 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 baru, class g_id_signin, dan objek g_id_onload menggantikan library apis.google.com/js/platform.js dan objek g-signin2 sebelumnya.

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

Meskipun tidak direkomendasikan karena meningkatkan kesulitan login, tombol personalisasi baru dapat ditampilkan sendiri, tanpa menampilkan dialog Login 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 fungsional, atau menggabungkan HTML API dan JavaScript API di seluruh situs Anda.

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

Login dari halaman mana pun dengan Login Sekali Ketuk

Login 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 membuka halaman login khusus. Dengan kata lain, cara 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 sertakan g_id_onload di header, footer, atau objek bersama lainnya yang disertakan di seluruh situs Anda.

Sebaiknya tambahkan g_id_signin, yang menampilkan tombol login yang dipersonalisasi, hanya di halaman login atau pengelolaan akun pengguna Anda. Berikan pilihan kepada pengguna untuk mendaftar atau login dengan menampilkan tombol di samping tombol penyedia identitas gabungan lainnya dan 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. Untuk penyederhanaan lebih lanjut, Anda tidak lagi diwajibkan menggunakan metode akses gaya "pengambil" untuk bekerja dengan data profil pengguna.

Kredensial token ID JWT yang ditandatangani Google yang aman akan ditampilkan:

• ke handler 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, 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-bidang credential dalam objek JWT CredentialResponse baru untuk menggunakan data profil pengguna.

Selain itu, dan hanya untuk mode Pengalihan, pastikan untuk mencegah Pemalsuan Permintaan Lintas Situs (CSRF) dan Verifikasi 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 spesifik yang digunakan.

Izin pengguna dan mencabut izin

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

Pengguna dapat mencabut izin dan membatalkan hubungan aplikasi Anda dari Akun Google mereka dengan membuka https://myaccount.google.com/permissions. Atau, mereka dapat berhenti terhubung langsung dari aplikasi Anda dengan memicu panggilan API yang Anda terapkan; metode disconnect sebelumnya telah digantikan oleh metode revoke yang lebih baru.

Saat pengguna menghapus akunnya di platform Anda, sebaiknya gunakan revoke untuk memutus koneksi aplikasi Anda dari Akun Google miliknya.

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

Status sesi dan Pemroses

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

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

Status login pengguna ke Akun Google mereka dan aplikasi Anda tidak saling terkait, kecuali selama proses login itu sendiri saat Anda mengetahui bahwa pengguna telah berhasil diautentikasi dan login ke Akun Google mereka.

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

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

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

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

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

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

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

Cookie

Login Dengan Google menggunakan cookie secara terbatas, deskripsi cookie ini tercantum di bawah. Lihat Cara Google menggunakan cookie untuk mengetahui informasi selengkapnya tentang jenis cookie lain yang digunakan oleh Google.

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

Library Google Identity Services yang baru dapat secara opsional menyetel 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 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 ditetapkan, atau

  • JavaScript API dengan ux_mode=redirect dan tempat 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 setelah migrasi selesai.

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

Referensi migrasi objek untuk login pengguna