Melakukan migrasi dari Login dengan Google

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

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

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

Autentikasi dan otorisasi

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

Seperti library platform Login dengan Google yang lebih lama, library Layanan Identitas Google yang baru dibuat untuk mendukung proses autentikasi dan otorisasi.

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

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

Jika kasus penggunaan Anda menyertakan otorisasi, baca Cara kerja otorisasi pengguna dan Bermigrasi ke Layanan Identitas Google untuk memastikan aplikasi Anda menggunakan API yang baru dan lebih baik.

Beberapa hal yang berubah

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

  • Alur Sekali Ketuk yang baru dan Login otomatis dengan langkah individual yang lebih sedikit,
  • 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 dan mudah mendaftar serta login dari mana saja di situs Anda tanpa harus mengunjungi halaman login atau akun terlebih dahulu.

Bagi developer, fokus kami adalah mengurangi kompleksitas, meningkatkan keamanan, dan membuat integrasi Anda secepat dan semudah mungkin. 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 OAuth2 tidak lagi diperlukan untuk membuat pengguna login ke situs Anda,
  • mode pop-up dan pengalihan terus didukung, tetapi infrastruktur OAuth2 Google kini dialihkan ke endpoint login server backend Anda,
  • konsolidasi fungsi dari library JavaScript Google Identity dan Google API lama ke dalam satu library baru,
  • untuk respons login, kini Anda dapat memutuskan apakah akan menggunakan Promise dan pengalihan langsung melalui fungsi gaya pengambil telah dihapus atau tidak.

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 dengan 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 yang lebih lama: 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 Layanan Identitas Google baru: accounts.google.com/gsi/client.

Tiga modul JavaScript lama: api, client, dan platform yang digunakan untuk login akan dimuat dari apis.google.com. Untuk membantu mengidentifikasi lokasi tempat library lama mungkin disertakan di situs Anda, biasanya:

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

Dalam sebagian besar kasus, Anda dapat terus menggunakan kredensial Client-ID aplikasi web yang sudah ada. Sebagai bagian dari migrasi, sebaiknya Anda meninjau Kebijakan OAuth 2.0 kami dan menggunakan Konsol API Google untuk mengonfirmasi, dan jika perlu, memperbarui setelan klien berikut:

  • aplikasi pengujian dan produksi Anda menggunakan Project terpisah dan memiliki Client-ID sendiri,
  • Jenis ID Klien 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 penghentian penggunaan.

Dalam aplikasi yang besar atau kompleks, mungkin akan sulit untuk menemukan semua kode yang terpengaruh oleh penghentian modul gapi.auth2. Untuk mencatat penggunaan yang sudah ada ke fungsi yang tidak digunakan lagi ke konsol ke dalam log, tetapkan nilai cookie G_AUTH2_MIGRATION ke informational. Secara opsional, tambahkan titik dua diikuti nilai kunci yang juga mencatat log ke penyimpanan sesi. Setelah login dan penerimaan kredensial, tinjau atau kirim log yang dikumpulkan ke backend untuk dianalisis nanti. Misalnya, informational:showauth2use menyimpan asal 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 penegakan.

Nilai cookie G_AUTH2_MIGRATION yang mungkin:

  • enforced Jangan memuat modul gapi.auth2.
  • informational Mencatat penggunaan fungsi yang tidak digunakan lagi ke konsol JS. Selain itu, catat ke penyimpanan sesi saat nama kunci opsional ditetapkan: informational:key-name.

Untuk meminimalkan dampak terhadap pengguna, sebaiknya tetapkan cookie ini secara lokal 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 respons autentikasi ditangani oleh callback JavaScript atau dengan pengalihan aman ke endpoint login server backend.

Cara lama

Merender tombol Login dengan Google dan menggunakan callback untuk menangani login secara langsung dari browser pengguna.

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

Mode pengalihan

Merender tombol Login dengan Google, yang diakhiri dengan panggilan AJAX dari browser pengguna ke endpoint login server backend Anda.

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

Hasil render

Atribut visual baru menyederhanakan metode lama pembuatan tombol yang disesuaikan, menghilangkan panggilan ke gapi.signin2.render(), dan tidak perlu lagi menghosting dan memelihara gambar dan aset visual di situs Anda.

Login dengan Google Login dengan Google

Teks tombol pembaruan status login pengguna.

Cara baru

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

Gunakan callback untuk menangani login langsung dari browser pengguna.

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

Mode pengalihan

Google memanggil endpoint login Anda seperti yang ditentukan oleh atribut data-login_url. Sebelumnya, Anda bertanggung jawab atas operasi dan parameter value POST. Library baru akan memposting token ID ke endpoint Anda di parameter credential. Terakhir, verifikasi token ID di server backend 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-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>

Hasil render

Gunakan visual-attribute untuk menyesuaikan ukuran, bentuk, dan warna tombol Login dengan Google. Tampilkan pop-up Sekali Ketuk beserta tombol yang dipersonalisasi untuk meningkatkan rasio login.

Tombol Login dengan Google Pop-up Sekali Ketuk

Status login pengguna tidak memperbarui teks tombol dari "Login" menjadi "Login". Setelah memberikan izin, atau pada kunjungan ulang, tombol yang dipersonalisasi menyertakan nama, email, dan foto profil pengguna.

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

Selain merender tombol baru yang dipersonalisasi, kode contoh juga menampilkan pop-up One Tap yang baru. Di mana pun Anda menampilkan tombol yang dipersonalisasi, kami juga sangat menyarankan agar Anda juga menampilkan pop-up Sekali Ketuk untuk meminimalkan hambatan pengguna selama pendaftaran dan login.

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

API HTML dan JavaScript

Contoh di atas menunjukkan cara menggunakan HTML API baru untuk menambahkan login ke situs Anda. Atau, Anda dapat menggunakan JavaScript API yang secara fungsional setara, atau menggabungkan dan mencocokkan HTML 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 Pembuat kode. Properti ini dapat digunakan untuk membandingkan berbagai opsi dan membuat cuplikan HTML dengan cepat untuk digunakan di situs Anda.

Login dari halaman apa pun dengan Sekali Ketuk

Sekali Ketuk adalah cara mudah baru bagi pengguna untuk mendaftar atau login ke situs Anda. Dengan fitur ini, Anda dapat mengaktifkan fitur login pengguna langsung dari halaman mana pun di situs Anda dan hal ini membuat pengguna tidak perlu lagi 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 apa pun, sebaiknya sertakan g_id_onload dalam header bersama, footer, atau objek lain yang disertakan di seluruh situs Anda.

Sebaiknya tambahkan 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 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 OAuth2, token akses, atau token refresh. Sebagai gantinya, Token ID JSON Web Token (JWT) digunakan untuk membagikan status login dan profil pengguna. Sebagai penyederhanaan lebih lanjut, Anda tidak perlu lagi menggunakan metode pengakses gaya "pengambil" untuk menangani data profil pengguna.

Kredensial token JWT yang ditandatangani Google yang aman akan ditampilkan:

  • ke pengendali callback JavaScript berbasis browser pengguna dalam mode Pop-up, atau
  • ke server backend melalui pengalihan Google ke endpoint login jika tombol Login dengan Google ux_mode ditetapkan 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 yang baru agar berfungsi dengan data profil pengguna.

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

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

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

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

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

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

Status dan Pemroses sesi

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 memengaruhi, kecuali selama proses login itu sendiri saat Anda tahu bahwa pengguna telah berhasil diautentikasi dan login ke Akun Google mereka.

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

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

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

Anda sekarang 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.

Cookie

Login dengan Google memanfaatkan cookie secara terbatas, deskripsi cookie ini mengikuti. Lihat Cara Google menggunakan cookie untuk informasi lebih lanjut tentang jenis cookie lain yang digunakan oleh Google.

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

Library Layanan Identitas Google yang 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 berikut saat menggunakan:

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

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

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

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

Referensi migrasi objek untuk login pengguna

Lama Baru Catatan
Library JavaScript
apis.google.com/js/platform.js accounts.google.com/gsi/client Ganti yang lama dengan yang baru.
apis.google.com/js/api.js accounts.google.com/gsi/client Ganti yang lama dengan yang baru.
Google Auth dan metode terkait:
GoogleAuth.AttachClickHandler() IdConfiguration.callback untuk data-callback JS dan HTML Ganti yang lama dengan yang baru.
GoogleAuth.currentUser.get() KredensialResponse Gunakan CredentialResponse sebagai gantinya, tidak lagi diperlukan.
GoogleAuth.currentUser.listen() Hapus. Status login pengguna saat ini di Google tidak tersedia. Pengguna harus login ke Google untuk mendapatkan izin dan momen login. Kolom select_by pada CredentialResponse dapat digunakan untuk menentukan hasil izin pengguna beserta metode login yang digunakan.
GoogleAuth.disconnect() google.accounts.id.revoke Ganti yang lama dengan yang baru. Pencabutan juga dapat dilakukan dari https://myaccount.google.com/permissions
GoogleAuth.grantOfflineAccess() Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
GoogleAuth.isSignedIn.get() Hapus. Status login pengguna saat ini di Google tidak tersedia. Pengguna harus login ke Google untuk mendapatkan izin dan momen login.
GoogleAuth.isSignedIn.listen() Hapus. Status login pengguna saat ini di Google tidak tersedia. Pengguna harus login ke Google untuk mendapatkan izin dan momen login.
GoogleAuth.signIn() Hapus. Pemuatan DOM HTML elemen g_id_signin atau panggilan JS ke google.accounts.id.renderButton akan memicu login pengguna ke Akun Google.
GoogleAuth.signOut() Hapus. Status login pengguna untuk aplikasi Anda dan Akun Google bersifat independen. Google tidak mengelola status sesi untuk aplikasi Anda.
GoogleAuth.then() Hapus. GoogleAuth tidak digunakan lagi.
GoogleUser dan metode terkait:
GoogleUser.disconnect() google.accounts.id.revoke Ganti yang lama dengan yang baru. Pencabutan juga dapat dilakukan dari https://myaccount.google.com/permissions
GoogleUser.getAuthResponse()
GoogleUser.getBasicProfile() KredensialResponse Langsung menggunakan credential dan sub-kolom, bukan metode BasicProfile.
GoogleUser.getGrantedScopes() Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
GoogleUser.getHostedDomain() KredensialResponse Sebagai gantinya, langsung gunakan credential.hd.
GoogleUser.getId() KredensialResponse Sebagai gantinya, langsung gunakan credential.sub.
GoogleUser.grantOfflineAccess() Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
GoogleUser.grant() Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
GoogleUser.hasGrantedScopes() Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
GoogleUser.isSignedIn() Hapus. Status login pengguna saat ini di Google tidak tersedia. Pengguna harus login ke Google untuk mendapatkan izin dan momen login.
GoogleUser.reloadAuthResponse() Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
Objek gapi.auth2 dan metode terkait:
Objek gapi.auth2.AuthorizeConfig Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
Objek gapi.auth2.AuthorizeResponse Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
Objek gapi.auth2.AuthResponse Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
gapi.auth2.otorisasi() Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
gapi.auth2.ClientConfig() Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
gapi.auth2.getAuthInstance() Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
gapi.auth2.init() Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
Objek gapi.auth2.OfflineAccessOptions Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
Objek gapi.auth2.SignInOptions Hapus. Token ID telah menggantikan cakupan dan token akses OAuth2.
Objek gapi.signin2 dan metode terkait:
gapi.signin2.render() Hapus. Pemuatan DOM HTML elemen g_id_signin atau panggilan JS ke google.accounts.id.renderButton akan memicu login pengguna ke Akun Google.