Eigene UI verwenden

Logto ermöglicht es dir, deine eigene UI mitzubringen, um die integrierte Anmeldeerfahrung vollständig zu ersetzen – zusätzlich zu den vorgefertigten UI-Anpassungsoptionen. Mit dieser Funktion kannst du eine ZIP-Datei mit deinen eigenen UI-Assets (HTML, CSS, JavaScript, Bilder usw.) hochladen, sie auf den Logto Cloud-Servern hosten lassen und sie als Anmeldeerfahrung für deine Tenant-Benutzer verwenden.

hinweis:

Diese Funktion erfordert, dass deine eigene UI mit Single Page Application (SPA) kompatibel ist. Es wird empfohlen, immer ein Produktions-Build für optimale Leistung zu verwenden.

Erkunde die Custom UI-Funktion in der Logto Console

Einstieg mit dem offiziellen Projekt

Der schnellste Weg, eine eigene Anmelde-UI zu starten, ist das Klonen des Logto Experience Projekts. Dies ist die integrierte Logto Sign-in Experience UI, die alle Funktionen und Best Practices von Logto abdeckt. Du kannst sie an deine Bedürfnisse anpassen.

Nachdem du den Code ausgecheckt hast, führe einfach folgenden Befehl aus, um das Projekt zu bauen:

pnpm install && pnpm build

hinweis:

Das gesamte Logto-Projekt ist ein pnpm Monorepo. Wenn du das Experience-Paket eigenständig (ohne pnpm) ausführen möchtest, ersetze workspace:-Abhängigkeiten in der package.json durch konkrete Versionsnummern (wie ^1.0.0).

Nach Abschluss des Builds findest du alle kompilierten Assets im dist-Verzeichnis. Erstelle dann ein ZIP-Archiv des dist-Verzeichnisses – dieses Archiv wird später zum Hochladen in Logto Cloud verwendet.

Anforderungen an Custom UI-Assets

Bevor du deine eigenen UI-Assets hochlädst, stelle sicher, dass sie folgende Anforderungen erfüllen:

• Die hochzuladenden Assets müssen als einzelne ZIP-Datei gepackt sein.
• Die ZIP-Datei muss eine index.html-Datei im Stammverzeichnis enthalten.
• Die ZIP-Datei darf 20 MB nicht überschreiten.
• Die ZIP-Datei darf keine Datei enthalten, die größer als 10 MB ist.
• Die ZIP-Datei darf insgesamt nicht mehr als 200 Dateien enthalten.

Eigene UI-Assets hochladen

hinweis:

Sei vorsichtig bei der Nutzung dieser Funktion in der Produktion, da sie die Anmeldeerfahrung deiner Nutzer sofort beeinflusst.

1. Navigiere zu Konsole > Anmeldung & Konto > Branding > Eigene UI verwenden.
2. Klicke, um deine im vorherigen Schritt erstellte ZIP-Datei auszuwählen oder ziehe sie per Drag & Drop hinein. Der Upload startet automatisch.
3. Nach Abschluss des Uploads speichere die Änderungen – deine eigene UI wird sofort bereitgestellt.
4. Das Fenster „Anmeldevorschau“ ist deaktiviert, wenn du deine eigene Anmelde-UI verwendest. Du kannst jedoch weiterhin auf die Schaltfläche „Live-Vorschau“ klicken, um deine eigene Anmeldeseite in einem neuen Browser-Tab zu testen.

Benutzerdefinierte CSP-Quellen konfigurieren

Logto setzt einen Content Security Policy (CSP)-Header auf benutzerdefinierten UI-Seiten. Wenn deine eigene UI Drittanbieter-Skripte lädt oder sich mit externen Diensten verbindet, füge die zusätzlichen Ursprünge unter Konsole > Anmeldung & Konto > Branding > Eigene UI verwenden hinzu.

Du kannst konfigurieren:

• script-src: Erlaubt JavaScript-Module oder Skriptquellen, z. B. CAPTCHA, Analytics oder Tag-Manager-Anbieter.
• connect-src: Erlaubt Netzwerkendpunkte, die von fetch, XMLHttpRequest, EventSource und WebSocket-Verbindungen genutzt werden.

Beispiel:

{
  "scriptSrc": ["https://scripts.example.com"],
  "connectSrc": ["https://api.example.com", "wss://events.example.com"]
}

Verwende für beide Direktiven HTTPS-Ursprünge. connect-src akzeptiert auch wss://-Ursprünge für WebSocket-Verbindungen. Logto fügt diese Quellen nur dann zur bestehenden Sicherheitsrichtlinie hinzu, wenn deine eigenen UI-Assets aktiv sind.

Cross-Origin-Opener-Policy-Header konfigurieren

Standardmäßig sendet Logto keinen Cross-Origin-Opener-Policy (COOP)-Header, sodass eine App, die die Anmeldeseite in einem Popup öffnet, weiterhin über window.opener mit ihr kommunizieren kann. Wenn deine Apps Benutzer nicht über Popups anmelden, kannst du deine eigene Anmelde-UI von anderen Browserfenstern isolieren. Wähle eine Richtlinie unter Cross-Origin-Opener-Policy in Konsole > Anmeldung & Konto > Branding > Eigene UI verwenden:

Option	Gesendeter Header	Wirkung
Nicht gesetzt (kein Header)	Keiner	Standard. Jede Popup-basierte Integration funktioniert weiterhin.
same-origin-allow-popups	Cross-Origin-Opener-Policy: same-origin-allow-popups	Trennt das Fenster ab, das die Anmeldeseite geöffnet hat. Popups, die deine eigene UI öffnet, behalten window.opener, solange sie auf anderen Seiten bleiben.
same-origin	Cross-Origin-Opener-Policy: same-origin	Trennt auch die Popups ab, die deine eigene UI öffnet.

Du kannst das Feld crossOriginOpenerPolicy auch mit der update sign-in experience Management API setzen. Es akzeptiert unsafe-none (Standard, sendet keinen Header), same-origin-allow-popups und same-origin.

warnung:

Bevor du eine Richtlinie auswählst, prüfe, wie deine Apps und deine eigene UI Popups verwenden:

• Apps, die die Anmeldeseite in einem Popup öffnen und auf window.opener angewiesen sind, z. B. um das Ergebnis per postMessage zu empfangen, funktionieren mit keiner der Richtlinien. Bleibe beim Standard, solange du solche Apps hast, oder stelle sie zuerst auf einen redirect-basierten Anmeldefluss um.
• Popups, die deine eigene UI öffnet, verlieren window.opener, sobald sie zu deiner eigenen UI zurücknavigieren, z. B. zu einer Social-Sign-in-Callback-Seite. Popups, die auf einer anderen Seite bleiben und ihr Ergebnis von dort senden, wie das Anmelde-Popup eines Anbieters, funktionieren mit same-origin-allow-popups weiterhin. Mit same-origin verlieren Popups window.opener sofort beim Öffnen.

Wenn du eine Richtlinie benötigst, bevorzuge same-origin-allow-popups gegenüber same-origin.

Logto sendet den Header nur, solange deine eigenen UI-Assets ausgeliefert werden. Die integrierten Anmeldeseiten, die /oidc/*-Seiten und das Account Center (/account) senden niemals einen COOP-Header, sodass Sicherheitsscanner ihn auf diesen Seiten weiterhin als fehlend melden können.

Entwickle deine eigene UI

Mit Experience API interagieren

Deine eigene UI muss mit der Experience API interagieren, um verschiedene Aktionen wie Anmeldung, Registrierung, Passwortzurücksetzung, Verknüpfung sozialer Konten, Aktivierung von MFA und mehr durchzuführen. Um die Benutzerflüsse und Implementierungsdetails besser zu verstehen, empfehlen wir, unser Experience API Design RFC zu lesen, das umfassende technische Spezifikationen und Beispiele bietet.

Du musst außerdem auf weitere Konfigurationen der Anmeldeerfahrung zugreifen, wie Branding-Farben, Firmenlogo, Favicon, Passwort-Richtlinie, lokalisierte Sprachphrasen und sogar benutzerdefiniertes CSS – über den sign-in Experience API endpoint.

CAPTCHA behandeln, wenn aktiviert

Die integrierte Logto-Anmeldeerfahrung behandelt CAPTCHA automatisch. Wenn dein Tenant „Eigene UI verwenden“ aktiviert und CAPTCHA-Bot-Schutz eingeschaltet ist, muss deine eigene UI die Frontend-CAPTCHA-Integration abschließen, bevor sie PUT /api/experience aufruft.

Sende das vom Anbieter zurückgegebene Token als captchaToken im Request-Body von PUT /api/experience. Siehe die anbieter-spezifischen Anleitungen für Details:

• reCAPTCHA Enterprise mit Eigene UI verwenden
• Cloudflare Turnstile mit Eigene UI verwenden

Beispielprojekte

Wir stellen eine Sammlung von Beispielprojekten bereit, um dir den Einstieg und das Verständnis für die Implementierung einer eigenen UI zu erleichtern. Sieh dir das Logto Experience project GitHub-Repository für Details an.

Darüber hinaus arbeiten wir kontinuierlich daran, weitere vereinfachte und szenariobasierte Beispielprojekte bereitzustellen, um die häufigsten Anwendungsfälle abzudecken. Bleib dran für zukünftige Updates!

Lokale Entwicklung und Debugging

Für die lokale Entwicklung und das Debugging stellen wir das Logto Tunnel CLI-Tool bereit, um:

• Experience API-Anfragen von deinem lokalen Rechner an den Logto Cloud-Endpunkt zu proxyen.
• Deine eigene UI-Implementierung lokal zu testen.

So können Nutzer ihre eigene UI lokal testen und debuggen, bevor sie sie in Logto Cloud hochladen.

Siehe Debugge und teste deine eigene UI lokal für weitere Details.

Eigene UI-Assets per CLI hochladen

Zusätzlich zum Hochladen über die Konsole kannst du auch das Logto CLI verwenden, um eigene UI-Assets hochzuladen. Das ist besonders nützlich für automatisierte Deployment-Workflows.

Siehe Eigene UI-Assets per CLI hochladen für weitere Details.

Wiederherstellung der integrierten Logto-Anmeldeerfahrung

Wenn du zur integrierten Logto-Anmeldeerfahrung zurückkehren möchtest, klicke einfach auf die Löschen-Schaltfläche auf der „Eigene UI verwenden“-Karte. Nach dem Speichern der Änderungen wird die Anmelde-UI wieder auf die Logto-Standardversion zurückgesetzt.

Verwandte Ressourcen

RFCS: Experience API

Experience-Beispiele Eigene Anmelde-UI zu Logto Cloud bringen