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.
Benutzer klickt den Link
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:
- Navigiere zu Console → Authentication → Passwordless
- Aktiviere Magic Links
- 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) - Konfiguriere Token Expiry — Standard ist 15 Minuten. Bereich: 5–60 Minuten
- 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
React
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:
| Szenario | Verhalten |
|---|---|
Bekannte E-Mail, allowSignup: true | Sendet Magic Link, authentifiziert bestehenden Benutzer |
Unbekannte E-Mail, allowSignup: true | Sendet Magic Link, erstellt neues Konto bei Verifizierung |
Unbekannte E-Mail, allowSignup: false | Gibt user_not_found-Fehler zurück, keine E-Mail gesendet |
Bekannte E-Mail, allowSignup: false | Sendet 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:
| Variable | Beschreibung |
|---|---|
{{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
/api/auth/magic-linkSendet 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.
/api/auth/magic-link/verifyVerifiziert 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
- Hosted Login (PKCE) — Der Standard-Interactive-Login-Flow
- SMS OTP — Telefonbasierte passwortlose Authentifizierung
- Passkeys / WebAuthn — Biometrische passwortlose Authentifizierung