Zum Hauptinhalt springen

Magic Link (Einmal-Token)

Ähnlich wie das Einmalpasswort (OTP) ist ein Einmal-Token eine weitere passwortlose Authentifizierungsmethode, die zur Verifizierung der Identität eines Benutzers verwendet 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. 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.

Anwendungsfälle​

Logto unterstützt die folgenden Szenarien mit Magic Links:

  • Registrierung nur auf Einladung: Für interne Tools oder KI-Produkte in der Testphase kannst du die öffentliche Registrierung deaktivieren und bestimmte Benutzer über Magic Links einladen.
  • Einladung von Organisationsmitgliedern: Für SaaS-Produkte kannst du Magic Links verwenden, um neue Mitglieder einzuladen, einer Organisation beizutreten, und so den Onboarding-Prozess zu vereinfachen.
  • Anmeldung / Registrierung: Sende einen Magic Link für passwortlose Anmeldung oder Registrierung per E-Mail.
  • Passwort zurücksetzen: Sende einen Magic Link zum Zurücksetzen des Passworts aus deiner eigenen Anwendung, damit der Benutzer das Einmal-Token verifizieren und ein neues Passwort in Logto festlegen kann.

Wenn du beispielsweise die öffentliche Registrierung deaktiviert hast, kannst du einen Magic Link mit einem Einmal-Token (z. B. https://yourapp.com/landing-page?token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]) an die E-Mail des Benutzers senden, um ihn zur Fertigstellung der Kontoerstellung einzuladen. Du kannst die E-Mail-Vorlage in deinem eigenen E-Mail-Zustelldienst anpassen, zum Beispiel:

Eine E-Mail-Vorlage für Registrierung nur auf Einladung

Derzeit nicht unterstützt:

  • Verwendung von Telefonnummer oder Benutzername als Identifikator.

Einmal-Token-Flow​

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 Request-Body:

{
  "email": "[email protected]",
  // Optional. Standardwert ist 600 (10 Minuten).
  "expiresIn": 3600,
  // Optional. Benutzer wird nach erfolgreicher Verifizierung den angegebenen Organisationen zugeordnet.
  "context": {
    "jitOrganizationIds": ["abcdefgh1234"]
  }
}

Für einen Magic Link zum Zurücksetzen des Passworts beschränke das Token auf den "Passwort vergessen"-Ablauf:

{
  "email": "[email protected]",
  "expiresIn": 3600,
  "context": {
    "interactionEvent": "ForgotPassword"
  }
}

Nachdem du das Einmal-Token erhalten hast, kannst du einen Magic Link erstellen und ihn an die E-Mail-Adresse des Endbenutzers senden. Für Anmelde- oder Registrierungs-Magic Links sollte der Link mindestens das Token und die Benutzer-E-Mail als Parameter enthalten. Für Magic Links zum Zurücksetzen des Passworts ist der E-Mail-Parameter optional; wenn du ihn weglässt, wird Logto den Benutzer bitten, seine E-Mail-Adresse einzugeben, bevor das Einmal-Token überprüft wird. Der Magic Link sollte 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 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​

Anmeldung oder Registrierung​

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 Redirect-URI für die Anmeldung
    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...</>;
};

Passwort zurücksetzen​

Für Magic Links zum Zurücksetzen des Passworts starte eine Authentifizierungsanfrage mit first_screen auf reset_password gesetzt. Übergebe das Einmal-Token über one_time_token. Wenn du die E-Mail des Benutzers bereits von deiner Landingpage hast, übergib sie über login_hint; andernfalls lasse login_hint weg und Logto wird den Benutzer bitten, seine E-Mail-Adresse vor der Token-Überprüfung einzugeben.

ResetPasswordTokenLandingPage.tsx
// React-Beispiel
import { useLogto } from '@logto/react';
import { useEffect } from 'react';
import { useSearchParams } from 'react-router-dom';

const ResetPasswordTokenLandingPage = () => {
  const { signIn } = useLogto();
  const [searchParams] = useSearchParams();

  useEffect(() => {
    const oneTimeToken = searchParams.get('token');
    const email = searchParams.get('email');

    if (oneTimeToken) {
      signIn({
        redirectUri: 'https://yourapp.com/callback',
        extraParams: {
          'one_time_token': oneTimeToken,
          'first_screen': 'reset_password',
          ...(email && { '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 aktuelle Authentifizierungsstatus 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 Anmelde-Callback-Seite löschen.

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

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

Wenn du clearTokens: false in der Anmeldefunktion angibst, musst du die Tokens manuell auf der Anmelde-Callback-Seite 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 Request-Body an.

Der Benutzer wird nach erfolgreicher Verifizierung automatisch den Organisationen hinzugefügt und Standardrollen der Organisation 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 weiterhin Magic Links verwenden, um Benutzer einzuladen, auch wenn du die Benutzerregistrierung unter "Anmeldung und Registrierung" 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 wird Logto das Einmal-Token trotzdem überprüfen und den Benutzer bei Bedarf den angegebenen Organisationen zuordnen.
  2. Der Benutzer ist bereits angemeldet und klickt dann auf einen Magic Link, der mit einem anderen Konto verknüpft ist. In diesem Fall wird Logto den Benutzer auffordern, 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, wird Logto das Token nicht überprüfen und zur Anwendung mit dem aktuellen Konto zurückkehren.
  3. Wenn dein Anmelde-Prompt auf "login" gesetzt ist oder "login" enthält, meldet Logto automatisch das mit dem Einmal-Token verknüpfte Konto an, ohne einen Kontowechsel abzufragen. Dies liegt daran, dass der "login"-Prompt eine explizite Authentifizierungsabsicht signalisiert, die Vorrang vor der aktuellen Sitzung hat.