Zum Hauptinhalt springen

Magic Link (Einmal-Token)

Cloud availabilityOSS availability

Ä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 nur 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:

Implementierungsleitfaden​

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 die 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": "[email protected]",
  // Optional. Standardwert ist 600 (10 Minuten).
  "expiresIn": 3600,
  // Optional. Der Benutzer wird nach erfolgreicher Verifizierung den angegebenen Organisationen zugeordnet.
  "context": {
    "jitOrganizationIds": ["abcdefgh1234"]
  }
}

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 zu einer 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 protected]
hinweis:

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.

TokenLandingPage.tsx
// 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(() => {
    // Extrahiere das Token und die E-Mail aus dem Magic Link
    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...</>;
};
warnung:

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 Authentifizierungsstatus des aktuellen Benutzers verloren geht.

Daher solltest du einen zusätzlichen Anmeldeparameter clearTokens: false angeben, um das Löschen der bestehenden Tokens zu vermeiden. Wenn dies angegeben ist, musst du die Tokens auch manuell auf der Callback-Seite der Anmeldung löschen.

Ignoriere dies, wenn deine Magic Links nicht für authentifizierte Benutzer gedacht sind.

Schritt 4: (Optional) Zwischengespeicherte Tokens auf der Callback-Seite löschen​

Wenn du clearTokens: false in der sign-in Funktion angibst, musst du die Tokens manuell auf der Callback-Seite der Anmeldung löschen.

Callback.tsx
// 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...</>;
};

FAQs​

Ja, du kannst den Magic Link verwenden, um neue Benutzer zu deiner Anwendung sowie zu Organisationen einzuladen. Wenn du neue Benutzer zu deiner Organisation einladen möchtest, gib einfach die jitOrganizationIds im Anfrage-Body an.

Der Benutzer wird nach erfolgreicher Verifizierung automatisch den Organisationen beitreten, und die Standardrollen der Organisation werden zugewiesen. Sieh dir den Abschnitt "Just-in-time-Bereitstellung" auf der Detailseite deiner Organisation an und konfiguriere die Standardrollen für deine Organisationen.

Der Magic Link Authentifizierungsablauf unterstützt keine Rollenzuweisung an Benutzer. Du kannst jedoch jederzeit die Webhooks und die Management API verwenden, um die Benutzerrollen nach der Registrierung zu aktualisieren.

Läuft das Einmal-Token ab?​

Ja, das Einmal-Token läuft nach der angegebenen expiresIn-Zeit (in Sekunden) ab. Die Standardablaufzeit beträgt 10 Minuten.

Ja, du kannst den Magic Link weiterhin zum Einladen von Benutzern verwenden, auch wenn du die Benutzerregistrierung in der "Anmeldeerfahrung" deaktivierst.

Es gibt mehrere mögliche Szenarien:

  1. Der Benutzer ist bereits angemeldet und klickt dann auf einen Magic Link, der mit dem aktuellen Benutzerkonto verknüpft ist. In diesem Fall überprüft Logto trotzdem das Einmal-Token und ordnet den Benutzer bei Bedarf den angegebenen Organisationen zu.
  2. Der Benutzer ist bereits angemeldet und klickt dann auf einen Magic Link, der mit einem anderen Konto verknüpft ist. In diesem Fall fordert Logto den Benutzer auf, entweder als neues Konto fortzufahren oder mit dem aktuellen Konto zur Anwendung zurückzukehren.
    1. Wenn der Benutzer sich entscheidet, als neues Konto fortzufahren, wechselt Logto nach erfolgreicher Token-Verifizierung zum neuen Konto.
    2. Wenn der Benutzer beim aktuellen Konto bleiben möchte, überprüft Logto das Token nicht und kehrt mit dem aktuellen Konto zur Anwendung zurück.
  3. Wenn dein Anmelde-Prompt auf "login" gesetzt ist oder "login" enthält, meldet Logto das mit dem Einmal-Token verknüpfte Konto automatisch an, ohne einen Wechsel abzufragen.