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
memuatapis.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 modulgapi.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
Mode pop-up
Render tombol Login dengan Google dan gunakan callback untuk menangani login 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
Render 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 sebelumnya untuk membuat tombol
yang disesuaikan, menghilangkan panggilan ke gapi.signin2.render()
, dan kebutuhan
untuk menghosting dan mengelola gambar dan aset visual di situs Anda.
Teks tombol pembaruan status login pengguna.
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.
Mode pop-up
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 nama parameter dan operasi POST. Library baru ini 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-attributes untuk menyesuaikan ukuran, bentuk, dan warna tombol Login dengan Google. Tampilkan pop-up Sekali Ketuk bersama dengan tombol yang dipersonalisasi untuk meningkatkan rasio login.
Status login pengguna tidak memperbarui teks tombol dari "Login" menjadi "Login". Setelah memberikan izin, atau saat terjadi kunjungan kembali, tombol yang dipersonalisasi akan menyertakan nama, email, dan foto profil pengguna.
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 keredirect
.
Dalam kedua kasus tersebut, perbarui pengendali callback yang ada dengan menghapus:
- panggilan ke
googleUser.getBasicProfile()
, - referensi ke
BasicProfile
, dan panggilan terkait ke metodegetId()
,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 saatdata-login_uri
disetel, atauJavaScript API dengan
ux_mode=redirect
dan yanggoogle.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
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. |
GoogleAuth dan metode terkait: | ||
GoogleAuth.attachClickHandler() | IdConfiguration.callback untuk data-callback JS dan HTML | Ganti yang lama dengan yang baru. |
GoogleAuth.currentUser.get() | CredentialResponse | Sebagai gantinya, gunakan CredentialResponse, 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 di 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 terjadi dari https://myaccount.google.com/permissions |
GoogleAuth.grantOfflineAccess() | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
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 terjadi dari https://myaccount.google.com/permissions |
GoogleUser.getAuthResponse() | ||
GoogleUser.getBasicProfile() | CredentialResponse | Menggunakan secara langsung credential dan sub-kolom, bukan metode BasicProfile . |
GoogleUser.getGrantedScopes() | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
GoogleUser.getHostedDomain() | CredentialResponse | Sebagai gantinya, langsung gunakan credential.hd . |
GoogleUser.getId() | CredentialResponse | Sebagai gantinya, langsung gunakan credential.sub . |
GoogleUser.grantOfflineAccess() | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
GoogleUser.grant() | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
GoogleUser.hasGrantedScopes() | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
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 OAuth 2.0. | |
gapi.auth2 dan metode terkait: | ||
Objek gapi.auth2.AuthorizeConfig | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
Objek gapi.auth2.AuthorizeResponse | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
Objek gapi.auth2.AuthResponse | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
{i>gapi.auth2.authorization()<i} | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
gapi.auth2.ClientConfig() | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
{i>gapi.auth2.getAuthInstance()<i} | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
{i>gapi.auth2.init()<i} | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
Objek gapi.auth2.OfflineAccessOptions | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
Objek gapi.auth2.SignInOptions | Hapus. Token ID telah menggantikan cakupan dan token akses OAuth 2.0. | |
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. |