Skip to Content

Magic Links (Passwortlose E-Mail)

Magic Links bieten ein passwortloses Authentifizierungserlebnis: Der Benutzer gibt seine E-Mail-Adresse ein, erhält einen Anmelde-Link und klickt darauf zur Authentifizierung – kein Passwort erforderlich. Auris übernimmt Token-Generierung, E-Mail-Zustellung und Verifizierung.

Magic Links eignen sich als eigenständige Anmeldemethode oder als sekundäre Option neben E-Mail/Passwort auf der gehosteten Login-Seite.


Funktionsweise

Benutzer sendet E-Mail

Deine Anwendung sendet die E-Mail-Adresse des Benutzers an den Auris Magic Link Endpunkt. Auris generiert einen kryptografisch zufälligen Einmal-Token, speichert dessen SHA-256-Hash und erstellt den Anmelde-Link.

Auris sendet die E-Mail

Auris stellt die Magic-Link-E-Mail über die auf deinem Tenant konfigurierte SMTP-Konfiguration zu. Der Link verweist auf die in Console → Authentication → Passwordless konfigurierte Redirect-URL, mit dem Token als Query-Parameter angehängt.

Der E-Mail-Client des Benutzers öffnet den Link. Die Seite unter deiner Redirect-URL extrahiert den Token aus der URL und ruft den Auris-Verifizierungs-Endpunkt auf.

Auris verifiziert den Token

Auris validiert den Token: Er muss vorhanden, nicht abgelaufen und nicht bereits verwendet worden sein. Bei Erfolg stellt Auris ein Access Token und Refresh Token aus.

Automatische Registrierung für neue E-Mails

Wenn allowSignup: true konfiguriert ist und die E-Mail in Auris nicht existiert, wird bei der Verifizierung automatisch ein neues Benutzerkonto erstellt. Der Benutzer wird sofort in das neue Konto authentifiziert.


Console-Konfiguration

Bevor du Magic Links verwendest, konfiguriere die Funktion in der Auris Console:

  1. Navigiere zu Console → Authentication → Passwordless
  2. Aktiviere Magic Links
  3. Setze die Redirect URL — die Seite in deiner Anwendung, die den Token empfängt und den Verify-Endpunkt aufruft (z. B. http://localhost:3000/auth/magic-link/verify)
  4. Konfiguriere Token Expiry — Standard ist 15 Minuten. Bereich: 5–60 Minuten
  5. Setze Allow Signup — wenn aktiviert, erstellt das Klicken eines Magic Links mit einer unbekannten E-Mail ein neues Konto

Die Redirect-URL muss in den erlaubten Callback-URLs deiner Anwendung registriert sein. Auris lehnt Magic-Link-Weiterleitungen zu nicht registrierten URLs ab.


Implementierung

import { useState } from 'react' import { useAuris } from '@auris/react' import { useSearchParams, useNavigate } from 'react-router-dom' // Magic-Link-Formular senden function MagicLinkForm() { const { loginWithMagicLink } = useAuris() const [email, setEmail] = useState('') const [sent, setSent] = useState(false) const [error, setError] = useState(null) async function handleSubmit(e) { e.preventDefault() const result = await loginWithMagicLink(email) if (result.success) { setSent(true) } else { setError(result.error) } } if (sent) { return ( <div> <h2>Prüfe deine E-Mails</h2> <p>Wir haben einen Anmelde-Link an {email} gesendet. Der Link läuft in 15 Minuten ab.</p> </div> ) } return ( <form onSubmit={handleSubmit}> <label>E-Mail-Adresse</label> <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} required /> {error && <p className="error">{error}</p>} <button type="submit">Anmelde-Link senden</button> </form> ) } // Verifizierungsseite — empfängt den Token vom E-Mail-Link function MagicLinkVerifyPage() { const { verifyMagicLink } = useAuris() const [searchParams] = useSearchParams() const navigate = useNavigate() useEffect(() => { const token = searchParams.get('token') if (!token) { navigate('/login?error=missing_token') return } verifyMagicLink(token).then((result) => { if (result.user) { navigate('/dashboard') } else { navigate('/login?error=invalid_token') } }) }, []) return <p>Dein Anmelde-Link wird verifiziert...</p> }

Verhalten der automatischen Registrierung

Wenn allowSignup: true in der Console konfiguriert ist, unterstützt der Magic-Link-Flow die Erstellung neuer Benutzerkonten:

SzenarioVerhalten
Bekannte E-Mail, allowSignup: trueSendet Magic Link, authentifiziert bestehenden Benutzer
Unbekannte E-Mail, allowSignup: trueSendet Magic Link, erstellt neues Konto bei Verifizierung
Unbekannte E-Mail, allowSignup: falseGibt user_not_found-Fehler zurück, keine E-Mail gesendet
Bekannte E-Mail, allowSignup: falseSendet Magic Link, authentifiziert bestehenden Benutzer

Wenn ein neues Konto via automatischer Registrierung erstellt wird, ist kein Passwort gesetzt. Der Benutzer kann später über die Kontoeinstellungen ein Passwort hinzufügen oder Magic Links weiterhin verwenden.


E-Mail-Vorlagen-Anpassung

Die Magic-Link-E-Mail verwendet die Vorlage Passwordless Login in Console → Authentication → Email Templates. Die Vorlage unterstützt folgende Variablen:

VariableBeschreibung
{{magic_link}}Die vollständige Anmelde-URL inklusive Token
{{user_email}}E-Mail-Adresse des Empfängers
{{expires_in}}Menschenlesbare Ablaufdauer (z. B. “15 Minuten”)
{{tenant_name}}Anzeigename deines Tenants
{{app_name}}Name der Anwendung, die den Login anfordert

Sicherheitsüberlegungen

Einmal-Tokens — Jeder Magic-Link-Token kann nur einmal verwendet werden. Das Klicken auf einen bereits verwendeten Link gibt einen token_already_used-Fehler zurück.

Token-Ablauf — Tokens laufen nach der konfigurierten Dauer ab (Standard: 15 Minuten). Abgelaufene Tokens geben einen token_expired-Fehler mit der Aufforderung zurück, einen neuen Link anzufordern.

Token-Hashing — Auris speichert nur den SHA-256-Hash des Tokens. Der Rohtoken ist nur in der E-Mail und der URL vorhanden — nie im Klartext in der Datenbank gespeichert.

Rate Limiting — Auris wendet Rate Limits auf den Magic-Link-Sende-Endpunkt an: maximal 5 Link-Anfragen pro E-Mail-Adresse pro Stunde. Dies verhindert E-Mail-Flooding-Missbrauch.

Kein Passwort erforderlich — Magic Links eignen sich für Benutzergruppen, bei denen Passwörter eine Hürde darstellen. Sie sind nicht schwächer als Passwörter, wenn Token-Ablauf und Einmal-Beschränkungen durchgesetzt werden.


API-Endpunkte

POST/api/auth/magic-link

Sendet eine Magic-Link-E-Mail an die angegebene E-Mail-Adresse. Body: { email: string }. Respektiert die allowSignup-Tenant-Konfiguration. Rate Limited: 5 Anfragen pro E-Mail pro Stunde.

POST/api/auth/magic-link/verify

Verifiziert einen Magic-Link-Token und stellt Access/Refresh-Tokens aus. Body: { token: string }. Der Token darf nicht abgelaufen oder zuvor verwendet worden sein.


Verwandte Anleitungen