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