Guida all’integrazione
Aggiungi «Accedi con Tutu» al tuo prodotto in quattro passaggi, con OAuth2 + PKCE.
Quattro passi per integrare
Il frontend avvia il login
Crea un’istanza con createTutuId({ baseUrl, clientId }) di @tutu/id-sdk e chiama idSdk.startLogin() al clic. L’SDK genera una coppia PKCE e reindirizza alla pagina di autorizzazione TutuId.
L’utente autorizza su TutuId
Nella schermata di consenso /oauth/authorize l’utente clicca «Consenti» (saltata se già autorizzato). Dopo aver verificato client_id e la allowlist redirect_uri, TutuId torna al tuo /auth/callback con un codice di autorizzazione.
La pagina di callback ottiene il code
Su /auth/callback chiama idSdk.completeCallback() per ottenere { code, codeVerifier }. Passa questi due valori al tuo backend; non scambiare mai il token direttamente nel browser.
Il backend scambia il token → crea l’account
Il tuo backend scambia code + codeVerifier per un access_token, chiama /userinfo per { sub, email, emailVerified, ... }, mappa o crea un account locale in base a sub, quindi emette la tua sessione.
★ Difesa dal furto di account (obbligatorio)
Il tuo backend può collegare o creare un account locale solo tramite sub (l’ID univoco dell’account). Solo quando emailVerified === true puoi collegare un account locale esistente tramite email; altrimenti crea un account separato e lascia vuota l’email.
Perché: un attaccante potrebbe pre-registrare un account Tutu con l’email di una vittima; unire tramite un’email non verificata consegnerebbe l’account locale della vittima. È una linea rossa di livello CVE.
Riferimento API dell’SDK
@tutu/id-sdk · puramente lato client, zero dipendenze (richiede Web Crypto + sessionStorage).
createTutuId({ baseUrl, clientId, redirectUri? }) Crea un’istanza dell’SDK. redirectUri predefinito è ${location.origin}/auth/callback, adattandosi a dev/prod.
startLogin(scope?) Genera una coppia PKCE e reindirizza alla pagina di autorizzazione, avviando «Accedi con Tutu».
trySilentLogin(scope?) Login silenzioso: se esiste una sessione centrale e un’autorizzazione precedente, scambia un codice senza interruzioni; altrimenti torna subito allo stato disconnesso (senza interrompere l’utente).
completeCallback() Analizza il risultato nella pagina di callback: in caso di successo restituisce { code, codeVerifier }, in caso di errore/annullamento restituisce { error }.
logoutEverywhere(returnTo?) Disconnette la sessione centrale, propagando il logout a tutti i prodotti della suite, poi torna a returnTo.
Vuoi prima vederlo in azione?