Magic Link (Einmal-Token)
Ähnlich wie das Einmalpasswort (OTP) ist ein Einmal-Token eine weitere passwortlose Authentifizierungsmethode, mit der die Identität eines Benutzers verifiziert werden kann. Das Token ist für einen begrenzten Zeitraum gültig und mit einer E-Mail-Adresse des Endbenutzers verknüpft.
Manchmal möchtest du neue Benutzer zu deiner Anwendung / Organisation einladen, ohne dass sie zuerst ein Konto erstellen müssen. Oder du hast dein Passwort vergessen und möchtest dich anmelden / dein Passwort zurücksetzen, indem du deine Identität schnell per E-Mail verifizierst. In solchen Fällen kann die Anwendung einen "Magic Link" an deine E-Mail senden. Und du wirst sofort authentifiziert, wenn du auf den Link klickst.
Anwendungsentwickler können das Einmal-Token verwenden, um einen Magic Link zu erstellen und ihn an die E-Mail-Adresse des Endbenutzers zu senden.
Einmal-Token-Ablauf
Hier ist das Sequenzdiagramm des Authentifizierungsablaufs mit Einmal-Token:
Implementierungsanleitung
Logto bietet eine Reihe von Management APIs und Experience APIs, um die Implementierung deines Magic Links zu erleichtern.
Bevor du beginnst, stelle sicher, dass du eine Logto-Instanz bereit hast und die Maschine-zu-Maschine-Verbindung zwischen deinem Anwendungsserver und dem Logto-Endpunkt hergestellt ist (erforderlich für die Management APIs). Erfahre mehr über Logto Management API.
Schritt 1: Einmal-Token anfordern
Verwende die Logto Management API, um ein Einmal-Token zu erstellen.
POST /api/one-time-tokens
Beispiel für den Anfrage-Body:
{
"email": "user@example.com",
// Optional. Standardwert ist 600 (10 Minuten).
"expiresIn": 3600,
// Optional. Der Benutzer wird nach erfolgreicher Verifizierung den angegebenen Organisationen zugeordnet.
"context": {
"jitOrganizationIds": ["abcdefgh1234"]
}
}
Schritt 2: Magic Link erstellen
Nachdem du das Einmal-Token erhalten hast, kannst du einen Magic Link erstellen und ihn an die E-Mail-Adresse des Endbenutzers senden.
Der Magic Link sollte mindestens das Token und die Benutzer-E-Mail als Parameter enthalten und auf eine Landingpage in deiner eigenen Anwendung führen.
Z. B. https://yourapp.com/landing-page.
Hier ist ein einfaches Beispiel, wie der Magic Link aussehen könnte:
https://yourapp.com/landing-page?token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&email=user@example.com
Die Parameternamen im Magic Link können vollständig angepasst werden. Du kannst dem Magic Link zusätzliche Informationen hinzufügen, je nach den Anforderungen deiner Anwendung, sowie alle URL-Parameter kodieren.
Schritt 3: Authentifizierungsablauf über Logto SDK auslösen
Nachdem der Endbenutzer auf den Magic Link geklickt und deine Anwendung aufgerufen hat, kannst du die Parameter token und email aus der URL extrahieren und dann die Funktion signIn() aus dem Logto SDK aufrufen, um den Authentifizierungsablauf zu starten.
// React-Beispiel
import { useLogto } from '@logto/react';
import { useEffect } from 'react';
import { useSearchParams } from 'react-router-dom';
const TokenLandingPage = () => {
const { signIn } = useLogto();
const [searchParams] = useSearchParams();
useEffect(() => {
// Token und E-Mail aus dem Magic Link extrahieren
const oneTimeToken = searchParams.get('token');
const email = searchParams.get('email');
// Dies ist deine sign-in redirect URI
const redirectUri = 'https://yourapp.com/callback';
if (oneTimeToken && email) {
signIn({
redirectUri,
clearTokens: false, // Optional. Siehe Warnhinweis unten
extraParams: {
'one_time_token': oneTimeToken,
'login_hint': email,
},
});
}
}, [searchParams, signIn]);
return <>Bitte warten...</>;
};
Wenn ein Benutzer bereits angemeldet ist, löscht der Aufruf der Funktion signIn() aus dem SDK automatisch alle zwischengespeicherten Tokens (ID-Token, Zugangstoken und Auffrischungstoken) aus dem Client-Speicher,
was dazu führt, dass der aktuelle Authentifizierungsstatus verloren geht.
Daher solltest du einen zusätzlichen sign-in Parameter clearTokens: false angeben, um das Löschen der bestehenden Tokens zu vermeiden.
Wenn dies angegeben ist, musst du die Tokens auf der sign-in Callback-Seite manuell löschen.
Ignoriere dies, wenn deine Magic Links nicht für authentifizierte Benutzer gedacht sind.
Schritt 4: (Optional) Zwischengespeicherte Tokens auf der sign-in Callback-Seite löschen
Wenn du clearTokens: false in der sign-in Funktion angibst, musst du die Tokens auf der sign-in Callback-Seite manuell löschen.
// React-Beispiel
import { useHandleSignInCallback, useLogto } from '@logto/react';
import { useEffect } from 'react';
const Callback = () => {
const { clearAllTokens } = useLogto();
useEffect(() => {
void clearAllTokens();
}, [clearAllTokens]);
useHandleSignInCallback(() => {
// Navigiere zu deiner Startseite
});
return <>Bitte warten...</>;
};