Panduan integrasi
Tambahkan «Masuk dengan Tutu» ke produk Anda dalam empat langkah dengan OAuth2 + PKCE.
Empat langkah integrasi
Frontend memulai login
Buat instance dengan createTutuId({ baseUrl, clientId }) dari @tutu/id-sdk, lalu panggil idSdk.startLogin() saat diklik. SDK membuat pasangan PKCE dan mengalihkan ke halaman otorisasi TutuId.
Pengguna mengotorisasi di TutuId
Di layar persetujuan /oauth/authorize pengguna klik «Izinkan» (dilewati otomatis jika sudah diotorisasi). Setelah TutuId memeriksa client_id dan allowlist redirect_uri, ia mengarahkan kembali ke /auth/callback Anda dengan kode otorisasi.
Halaman callback mengambil code
Di /auth/callback panggil idSdk.completeCallback() untuk mendapat { code, codeVerifier }. Serahkan dua nilai ini ke backend Anda sendiri; jangan pernah menukar token langsung di browser.
Backend menukar token → membuat akun
Backend Anda menukar code + codeVerifier menjadi access_token, memanggil /userinfo untuk { sub, email, emailVerified, ... }, memetakan atau membuat akun lokal berdasarkan sub, lalu menerbitkan sesi Anda sendiri.
★ Pertahanan pengambilalihan akun (wajib)
Backend Anda hanya boleh menautkan atau membuat akun lokal berdasarkan sub (ID akun unik). Hanya bila emailVerified === true Anda boleh menautkan akun lokal yang ada berdasarkan email; jika tidak, buat akun terpisah dan kosongkan email.
Mengapa: penyerang bisa mendaftarkan akun Tutu lebih dulu dengan email korban; menggabungkan berdasarkan email yang belum terverifikasi berarti menyerahkan akun lokal korban. Ini garis merah tingkat CVE.
★ Percabangkan proses keluar: untuk akun terdaftar lokal (tidak tertaut ke Tutu ID), JANGAN panggil logoutEverywhere() — itu akan mengakhiri sesi pusat Tutu ID yang tidak berkaitan di peramban dan mengeluarkan pengguna dari seluruh rangkaian produk. Dia hanya ingin keluar dari produk Anda. Kaskadekan hanya jika akun memang tertaut.
Referensi API SDK
@tutu/id-sdk · murni sisi klien, tanpa dependensi (butuh Web Crypto + sessionStorage).
createTutuId({ baseUrl, clientId, redirectUri? }) Membuat instance SDK. redirectUri default-nya ${location.origin}/auth/callback, menyesuaikan dev/prod.
startLogin(scope?) Membuat pasangan PKCE dan mengalihkan ke halaman otorisasi, memulai «Masuk dengan Tutu».
trySilentLogin(scope?) Login senyap: jika ada sesi pusat dan otorisasi sebelumnya, menukar kode secara mulus; jika tidak, langsung kembali ke keadaan keluar (tanpa mengganggu pengguna).
completeCallback() Mengurai hasil di halaman callback: saat berhasil mengembalikan { code, codeVerifier }, saat gagal/batal mengembalikan { error }.
logoutEverywhere(returnTo?) Keluar dari sesi pusat, mengeluarkan berantai semua produk suite, lalu kembali ke returnTo.
Ingin melihatnya beraksi dulu?