Integrationsleitfaden
Fügen Sie „Mit Tutu anmelden“ in vier Schritten zu Ihrem Produkt hinzu – mit OAuth2 + PKCE.
Vier Schritte zur Integration
Frontend startet die Anmeldung
Erstellen Sie mit createTutuId({ baseUrl, clientId }) aus @tutu/id-sdk eine Instanz und rufen Sie beim Klick idSdk.startLogin() auf. Das SDK erzeugt ein PKCE-Paar und leitet zur TutuId-Autorisierungsseite weiter.
Nutzer autorisiert auf TutuId
Auf dem Zustimmungsbildschirm /oauth/authorize klickt der Nutzer „Erlauben“ (bei bereits erteilter Autorisierung übersprungen). Nach Prüfung von client_id und der redirect_uri-Whitelist leitet TutuId mit einem Autorisierungscode zurück zu Ihrem /auth/callback.
Callback-Seite holt den Code
Rufen Sie auf /auth/callback idSdk.completeCallback() auf, um { code, codeVerifier } zu erhalten. Übergeben Sie diese beiden Werte Ihrem eigenen Backend – tauschen Sie das Token nie direkt im Browser.
Backend tauscht Token → erstellt Konto
Ihr Backend tauscht code + codeVerifier gegen ein access_token, ruft /userinfo für { sub, email, emailVerified, ... } auf, ordnet per sub ein lokales Konto zu oder erstellt es und stellt dann Ihre eigene Sitzung aus.
★ Schutz vor Konto-Übernahme (unbedingt beachten)
Ihr Backend darf ein lokales Konto nur per sub (die eindeutige Konto-ID) verknüpfen oder erstellen. Nur wenn emailVerified === true, dürfen Sie ein bestehendes lokales Konto per E-Mail verknüpfen; andernfalls erstellen Sie ein separates Konto und lassen die E-Mail leer.
Warum: Ein Angreifer könnte mit der E-Mail eines Opfers ein Tutu-Konto vorab registrieren; ein Zusammenführen über eine unverifizierte E-Mail würde das lokale Konto des Opfers preisgeben. Das ist eine rote Linie auf CVE-Niveau.
SDK-API-Referenz
@tutu/id-sdk · rein clientseitig, ohne Abhängigkeiten (benötigt Web Crypto + sessionStorage).
createTutuId({ baseUrl, clientId, redirectUri? }) Erstellt eine SDK-Instanz. redirectUri ist standardmäßig ${location.origin}/auth/callback und passt sich dev/prod an.
startLogin(scope?) Erzeugt ein PKCE-Paar und leitet zur Autorisierungsseite weiter, um „Mit Tutu anmelden“ zu starten.
trySilentLogin(scope?) Silent-Login: Bei zentraler Sitzung und vorheriger Autorisierung wird nahtlos ein Code getauscht; andernfalls sofort auf abgemeldeten Zustand zurückfallen (ohne den Nutzer zu unterbrechen).
completeCallback() Wertet das Ergebnis auf der Callback-Seite aus: bei Erfolg { code, codeVerifier }, bei Fehler/Abbruch { error }.
logoutEverywhere(returnTo?) Meldet die zentrale Sitzung ab, meldet kaskadierend alle Produkte der Suite ab und kehrt dann zu returnTo zurück.
Möchten Sie es zuerst in Aktion sehen?