Zum Hauptinhalt springen

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 Mandantenbenutzer 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 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 Verwendung dieser Funktion in der Produktion, da sie sofort die Anmeldeerfahrung deiner Benutzer 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.

Eigene CSP-Quellen konfigurieren​

Logto wendet einen Content Security Policy (CSP)-Header auf eigene UI-Seiten an. Wenn deine eigene UI Drittanbieter-Skripte lädt oder Verbindungen zu externen Diensten herstellt, füge die zusätzlichen erlaubten Origins unter Konsole > Anmeldung & Konto > Branding > Eigene UI verwenden hinzu.

Du kannst Folgendes konfigurieren:

  • script-src: Erlaubt JavaScript module- oder script-Quellen, zum Beispiel CAPTCHA-, Analytics- oder Tag-Manager-Anbieter.
  • connect-src: Erlaubt Netzwerk-Endpunkte, die von fetch, XMLHttpRequest, EventSource und WebSocket-Verbindungen verwendet werden.

Beispiel:

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

Verwende HTTPS-Origins für beide directives. connect-src akzeptiert außerdem wss://-Origins für WebSocket-Verbindungen. Logto hängt diese Quellen nur dann an die bestehende Sicherheitsrichtlinie an, wenn deine eigenen UI-Assets aktiv sind.

Entwickle deine eigene UI​

Interaktion mit Experience API​

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 eigenes CSS – über den Sign-in Experience API Endpoint.

CAPTCHA behandeln, wenn aktiviert​

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

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

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. Schau dir das Logto Experience Projekt 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 Benutzer 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.

RFCS: Experience API

 Experience-Beispiele Eigene Anmelde-UI zu Logto Cloud bringen