Guide d’intégration
Ajoutez « Se connecter avec Tutu » à votre produit en quatre étapes, avec OAuth2 + PKCE.
Quatre étapes pour intégrer
Le frontend lance la connexion
Créez une instance avec createTutuId({ baseUrl, clientId }) de @tutu/id-sdk et appelez idSdk.startLogin() au clic. Le SDK génère une paire PKCE et redirige vers la page d’autorisation TutuId.
L’utilisateur autorise sur TutuId
Sur l’écran de consentement /oauth/authorize, l’utilisateur clique sur « Autoriser » (ignoré s’il a déjà autorisé). Après vérification de client_id et de la liste blanche redirect_uri, TutuId revient vers votre /auth/callback avec un code d’autorisation.
La page de callback récupère le code
Sur /auth/callback, appelez idSdk.completeCallback() pour obtenir { code, codeVerifier }. Transmettez ces deux valeurs à votre propre backend ; n’échangez jamais le token directement dans le navigateur.
Le backend échange le token → crée le compte
Votre backend échange code + codeVerifier contre un access_token, appelle /userinfo pour obtenir { sub, email, emailVerified, ... }, mappe ou crée un compte local par sub, puis émet votre propre session.
★ Défense anti-usurpation de compte (impératif)
Votre backend ne peut lier ou créer un compte local que par sub (l’ID unique du compte). Uniquement lorsque emailVerified === true, vous pouvez lier un compte local existant par e-mail ; sinon, créez un compte distinct et laissez l’e-mail vide.
Pourquoi : un attaquant pourrait préenregistrer un compte Tutu avec l’e-mail d’une victime ; fusionner via un e-mail non vérifié livrerait le compte local de la victime. C’est une ligne rouge de niveau CVE.
★ Différenciez la déconnexion : pour les comptes créés localement (non liés à Tutu ID), n’appelez PAS logoutEverywhere() — cela fermerait la session centrale Tutu ID du navigateur et déconnecterait l’utilisateur de toute la suite. Il voulait seulement quitter votre produit. Ne propagez que si le compte est réellement lié.
Référence de l’API du SDK
@tutu/id-sdk · entièrement côté client, sans dépendances (nécessite Web Crypto + sessionStorage).
createTutuId({ baseUrl, clientId, redirectUri? }) Crée une instance du SDK. redirectUri vaut par défaut ${location.origin}/auth/callback, s’adaptant à dev/prod.
startLogin(scope?) Génère une paire PKCE et redirige vers la page d’autorisation, lançant « Se connecter avec Tutu ».
trySilentLogin(scope?) Connexion silencieuse : s’il existe une session centrale et une autorisation préalable, échange un code de façon transparente ; sinon, retombe aussitôt à l’état déconnecté (sans interrompre l’utilisateur).
completeCallback() Analyse le résultat sur la page de callback : en cas de succès renvoie { code, codeVerifier }, en cas d’échec/annulation renvoie { error }.
logoutEverywhere(returnTo?) Déconnecte la session centrale, en cascade sur tous les produits de la suite, puis revient à returnTo.
Envie de le voir en action d’abord ?