Zum Hauptinhalt springen

Benutzerdefinierte Domains

hinweis:

Das Ändern der Domain nach der Veröffentlichung deines Dienstes kann zu Problemen führen, da dein Anwendungscode und Integrationen möglicherweise noch auf die alte Domain verweisen. Um einen reibungslosen Übergang zu gewährleisten, empfehlen wir, deine benutzerdefinierten Domains direkt zu Beginn bei der Erstellung des Production-Tenants einzurichten.

Dein Logto-Tenant wird mit einer standardmäßigen, kostenlosen Domain {{tenant-id}}.app.logto bereitgestellt. Du kannst jedoch das Benutzererlebnis und die Markenwahrnehmung verbessern, indem du benutzerdefinierte Domains wie auth.example.com verwendest.

Deine benutzerdefinierten Domains werden für mehrere Funktionen verwendet:

Mehrere benutzerdefinierte Domains​

Logto unterstützt jetzt die Konfiguration von mehreren benutzerdefinierten Domains für einen einzelnen Tenant, sodass deine Anmeldeseite über mehr als eine gebrandete Domain erreichbar ist.

Planbasierte Limits:

  • Development-Tenant: Bis zu 2 benutzerdefinierte Domains kostenlos hinzufügen (zu Testzwecken)
  • Free-Plan: 1 benutzerdefinierte Domain kostenlos hinzufügen
  • Pro-Plan: 1 benutzerdefinierte Domain inklusive, mit der Möglichkeit, insgesamt bis zu 10 benutzerdefinierte Domains über Add-ons hinzuzufügen
  • Enterprise-Plan: Für mehr als 10 benutzerdefinierte Domains oder individuelle Anforderungen bitte kontaktiere uns

Siehe die Logto-Preistabelle für detaillierte Informationen.

Mit mehreren benutzerdefinierten Domains kannst du:

  • Verschiedene Domains für verschiedene Regionen, Sprachen, Anwendungen, Organisationen oder Top-Level-Domains verwenden
  • Vertrauen aufbauen, indem du ein konsistentes Markenerlebnis vor und nach der Anmeldung beibehältst
  • Regions- oder markenspezifische Authentifizierungserfahrungen durch Custom UI bereitstellen

Benutzerdefinierte Domains in der Console konfigurieren​

Um eine neue benutzerdefinierte Domain in der Logto Console hinzuzufügen, folge diesen Schritten:

  1. Navigiere zu Console > Einstellungen > Domains.

  2. Gib im Abschnitt "Benutzerdefinierte Domain hinzufügen" deine Subdomain ein (z. B. auth.example.com, auth.us.example.com) und klicke auf "Domain hinzufügen".

    Domain hinzufügen

  3. Kopiere den CNAME-Wert domains.logto.app aus der Tabelle und gehe zu deinem DNS-Anbieter, um den Eintrag hinzuzufügen.

    Benutzerdefinierte Domain wird verarbeitet

  4. Warte auf die Verifizierung und den SSL-Prozess.

    1. Wir überprüfen deine Einträge automatisch alle 10 Sekunden, bis die benutzerdefinierte Domain hinzugefügt wurde. Stelle einfach sicher, dass der eingegebene Domainname bzw. die DNS-Einträge korrekt sind.
    2. Die Verifizierung dauert in der Regel nur wenige Minuten, kann aber je nach DNS-Anbieter bis zu 24 Stunden dauern. Du kannst währenddessen die Seite verlassen.

Um mehrere benutzerdefinierte Domains hinzuzufügen, wiederhole die obigen Schritte für jede gewünschte Domain.

Domain-Verifizierungsdateien​

Einige Drittanbieter-Plattformen verlangen, dass du eine kleine Text- oder JSON-Datei auf deiner Domain hostest, um den Besitz nachzuweisen, bevor du deren OAuth-, SSO- oder andere Integrationen nutzen kannst. Da eine Logto-Benutzerdefinierte Domain auf Logto Cloud zeigt, kannst du diese Datei nicht auf deinem eigenen Ursprung hochladen. Logto kann diese Dateien für dich hosten.

Nachdem eine benutzerdefinierte Domain Aktiv ist, öffne die Domain-Karte in Console > Einstellungen > Domains und verwende den Abschnitt Domain-Verifizierungsdateien, um Dateien hinzuzufügen, zu aktualisieren oder zu entfernen.

Unterstützte Pfade

  • Dateinamen auf Root-Ebene mit Erweiterung, wie /MP_verify_xxx.txt oder /apple-developer-domain-association.txt
  • Pfade unter /.well-known/, wie /.well-known/apple-developer-domain-association.txt

Nur Buchstaben, Zahlen, Punkte, Bindestriche und Unterstriche sind in den Pfadsegmenten erlaubt. Verschachtelte Pfade außerhalb von /.well-known/ werden nicht unterstützt.

Limits

  • Bis zu 10 Verifizierungsdateien pro benutzerdefinierter Domain
  • Dateigröße bis zu 16.384 Zeichen pro Datei
  • Inhaltstyp: Klartext (text/plain) oder JSON (application/json)

Nach dem Speichern stellt Logto eine exakte Übereinstimmung für GET- und HEAD-Anfragen auf der benutzerdefinierten Domain bereit, zum Beispiel:

https://auth.example.com/MP_verify_xxx.txt
https://auth.example.com/.well-known/apple-developer-domain-association.txt

Bestehende Logto-Routen haben immer Vorrang. Verifizierungsdateien werden nur bereitgestellt, wenn kein anderer Logto-Handler mit dem Pfad übereinstimmt.

Fehlerbehebung​

SSL-Zertifikat-Probleme​

Wenn du beim Einrichten deiner benutzerdefinierten Domain auf SSL-Zertifikat-Probleme stößt, kann dies an CAA-Einträgen in deiner DNS-Konfiguration liegen. CAA-Einträge legen fest, welche Zertifizierungsstellen (CAs) berechtigt sind, Zertifikate für deine Domain auszustellen. Wenn du CAA-Einträge verwendest, musst du sowohl "letsencrypt.org" als auch "pki.goog" autorisieren, damit Logto SSL-Zertifikate ausstellen kann.

Zur Fehlerbehebung und Lösung von SSL-Zertifikat-Problemen im Zusammenhang mit CAA-Einträgen siehe die Cloudflare-Dokumentation zu CAA-Einträgen.

Fehler "The hostname is associated with a held zone"​

Wenn du die Fehlermeldung "The hostname is associated with a held zone, please contact the owner to have the hold removed" beim Hinzufügen einer benutzerdefinierten Domain erhältst, bedeutet dies, dass die Domain bereits in einer Cloudflare-Zone ist und auf den Status "Zone Hold" gesetzt wurde. Siehe diese Cloudflare-Dokumentation für weitere Informationen.

Um dieses Problem zu lösen, musst du den Zone Hold aufheben. Folge dem obigen Link für Anweisungen zum Aufheben des Zone Hold in Cloudflare.

Verbindungstimeout (Fehlercode 522) für auf Cloudflare gehostete Domain​

Wenn deine Domain bei Cloudflare gehostet wird, deaktiviere den Cloudflare-Proxy für den CNAME-Eintrag.

Fehler "Redirect URI does not match" nach Einrichtung der benutzerdefinierten Domain​

Wenn du nach dem Hinzufügen deiner benutzerdefinierten Domain den Fehler "redirect URI does not match" erhältst, musst du deine SDK-Konfiguration aktualisieren, damit der Endpunkt die benutzerdefinierte Domain verwendet.

Zum Thema "primäre Domain":

Es gibt keine separate Einstellung für eine "primäre Domain" in Logto. Nach dem Hinzufügen einer benutzerdefinierten Domain bleiben sowohl deine benutzerdefinierte Domain als auch die Standard-Domain {tenant-id}.logto.app gültig. Die Domain, die du im endpoint-Parameter deines SDKs konfigurierst, bestimmt, welche Domain für Authentifizierungsabläufe verwendet wird.

Lösung:

Aktualisiere den endpoint-Parameter in deiner SDK-Initialisierung, um deine benutzerdefinierte Domain zu verwenden:

const client = new LogtoClient({
  endpoint: 'https://auth.example.com', // Verwende deine benutzerdefinierte Domain
  appId: 'your-app-id',
  // ... weitere Optionen
});

Überprüfe außerdem, ob die in Console → Anwendungen registrierten Redirect-URIs mit der verwendeten Domain übereinstimmen.

Hinweis: Logto stellt SSL-Zertifikate für deine benutzerdefinierte Domain automatisch bereit und verwaltet sie. Du musst keine eigenen Zertifikate konfigurieren.

Benutzerdefinierte Domains verwenden​

Sobald du deine Einstellungen konfiguriert hast, stehen sowohl dein benutzerdefinierter Domainname als auch der Standard-Logto-Domainname für deinen Tenant zur Verfügung. Für die Aktivierung deines benutzerdefinierten Domainnamens sind jedoch bestimmte Konfigurationen erforderlich.

hinweis:

In diesem Artikel gehen wir davon aus, dass deine benutzerdefinierte Domain auth.example.com ist.

Aktualisierung des SDK-Endpunkts für Anwendungen​

Passe deinen Initialisierungscode für das Logto SDK an, indem du den Domainnamen des Endpunkts änderst.

const client = new LogtoClient({
  ...,// weitere Optionen
  endpoint: 'https://auth.example.com',
});

Auf der Detailseite deiner Anwendung in Console > Anwendungen scrolle zum Abschnitt "Endpoints & Credentials". Wechsle das Domain-Dropdown, um die entsprechenden Endpunkte anzuzeigen und für deine Anwendungseinstellungen zu kopieren.

Auth-Endpunkte für andere Anwendungen anpassen​

Wenn du Anwendungen hast, die nicht das Logto SDK verwenden, musst du deren Auth-Endpunkte aktualisieren.

Du findest die Auth-Endpunkte unter der Well-known-URL:

https://auth.example.com/oidc/.well-known/openid-configuration

Redirect-URIs für soziale Connectors aktualisieren​

Soziale Connectors verwenden das OIDC/OAuth-Protokoll. Wenn sich Benutzer über eine benutzerdefinierte Domain anmelden, wird die Redirect-URI automatisch auf diese benutzerdefinierte Domain gesetzt. Du musst die Redirect-URI in der Entwicklerkonsole deines Social-Providers aktualisieren.

Schritte:

  1. Navigiere zu Console > Connectors > Social Connectors und wähle deinen Connector aus.
  2. Kopiere die in den Connector-Details angezeigte Redirect-URI. Logto listet alle verfügbaren Redirect-URIs für deine konfigurierten benutzerdefinierten Domains auf.
  3. Füge diese Redirect-URI in der Entwicklerkonsole deines Social-Providers hinzu (z. B. Google, GitHub, Facebook).

Für mehrere benutzerdefinierte Domains:

  • Füge alle Redirect-URIs für jede konfigurierte benutzerdefinierte Domain hinzu. So funktioniert die soziale Anmeldung unabhängig davon, über welche Domain Benutzer zugreifen.
  • Die Standard-Logto-Domain (*.logto.app) bleibt gültig. Füge sie nur hinzu, wenn du auch Anmeldungen über die Standard-Domain unterstützen möchtest.
  • Für den GitHub-Connector verwende GitHub Apps anstelle von OAuth-Apps, die im GitHub-Dashboard konfiguriert sind, da GitHub Apps mehrere Redirect-URIs unterstützen. OAuth-Apps unterstützen nur eine einzelne Redirect-URI.

Redirect-URIs für OIDC-basierte Enterprise SSO Connectors aktualisieren​

OIDC-basierte Enterprise Connectors folgen demselben Muster wie soziale Connectors.

Schritte:

  1. Navigiere zu Console > Enterprise SSO und wähle deinen OIDC-Connector aus.
  2. Kopiere die Redirect-URIs aus den Connector-Details. Logto listet alle verfügbaren Redirect-URIs für deine konfigurierten benutzerdefinierten Domains auf.
  3. Aktualisiere die Redirect-URI in den Einstellungen deines Identitätsanbieters (IdP).

Für mehrere benutzerdefinierte Domains: Füge alle entsprechenden Redirect-URIs zu deinem IdP hinzu, damit Enterprise SSO auf allen Domains funktioniert.

ACS-URLs für SAML-basierte Enterprise SSO Connectors aktualisieren​

SAML-basierte Enterprise Connectors verwenden eine Assertion Consumer Service (ACS)-URL anstelle einer Redirect-URI.

Schritte:

  1. Navigiere zu Console > Enterprise SSO und wähle deinen SAML-Connector aus.
  2. Im Abschnitt "Im IdP konfigurieren" kannst du über das Domain-Dropdown zwischen deinen benutzerdefinierten Domains wechseln.
  3. Kopiere die ACS-URL für die gewünschte Domain.
  4. Füge diese ACS-URLs in die Konfiguration deines SAML-Identitätsanbieters ein.

Wichtig: Die ausgewählte Domain bestimmt, wohin Benutzer nach der SSO-Authentifizierung weitergeleitet werden. Konfiguriere dies entsprechend der Domain, auf der deine Anwendung die SAML-Antwort erwartet.

Passkey für MFA und Anmeldung​

Passkeys für Multi-Faktor-Authentifizierung (MFA) und Passkey-Anmeldung sind an die Domain gebunden, auf der sie registriert wurden. Benutzer müssen sich über dieselbe Domain anmelden, um ihre Passkeys zu verwenden.

Aktuelle Einschränkung: Logto unterstützt derzeit noch keine domänenübergreifende Passkey-Verifizierung. Wenn ein Benutzer einen Passkey auf auth.us.example.com registriert, muss er sich über auth.us.example.com anmelden, um diesen Passkey für die MFA-Verifizierung oder Passkey-Anmeldung zu verwenden. Ein auf einer Domain registrierter Passkey kann nicht verwendet werden, wenn die Anmeldung über eine andere benutzerdefinierte Domain erfolgt.