Connector-Datenstruktur

Einführung

Was ist ein Connector?

Connectors spielen eine entscheidende Rolle in Logto. Mit ihrer Hilfe ermöglicht Logto Endbenutzern die passwortlose Registrierung oder Anmeldung sowie die Möglichkeit, sich mit sozialen Konten anzumelden. Mit der zunehmenden Beliebtheit von Websites und Anwendungen ermöglichen passwortlose und soziale Anmeldungen den Benutzern, das Verwalten zahlreicher Konten und Passwörter zu vermeiden.

Folge unseren Connector-Anleitungen, wenn du einen bestehenden Connector einrichten möchtest. Wenn du den gewünschten Connector nicht findest, kannst du diese Connectoren entwickeln, indem du den Anleitungen in Entwickle deinen Connector folgst.

Zusammensetzungen

Es gibt viele Eigenschaften in den Connector-Daten.

Um das Laden und Aktualisieren der Daten effizienter zu gestalten, speichern wir einen Teil der Connector-Daten, die häufig geändert werden, in der DB und den Rest lokal.

• Lokaler Speicher, auch bekannt als ConnectorMetadata, ist ein Objekt, das feste Eigenschaften wie Logo, Connector-Typ usw. enthält. (:face_with_monocle: Schwierigkeiten beim Verständnis dieser Eigenschaften? Keine Sorge, eine detaillierte Erklärung folgt später!)
• Remote-Speicher wird in der DB gespeichert, um relativ häufige Änderungen an diesen Daten zu ermöglichen.

Lokaler Speicher des Connectors: ConnectorMetadata

id

id ist ein eindeutiger string-typisierter Schlüssel, um einen Connector in Logto zu identifizieren.

Er wird von den Entwicklern jedes Connectors zugewiesen und in die DB hochgeladen.

target

target ist ein Kleinbuchstaben-String, um die Quelle der sozialen Identitäten des sozialen Connectors zu unterscheiden.

Logto-Benutzer können diese Variable als "Name des Identitätsanbieters" betrachten, um sie besser zu verstehen.

Zum Beispiel sollte dein target google sein, wenn du dich mit deinem Google-Konto bei Logto anmeldest. Der Wert von target kann ein beliebiger nicht-leerer String sein, aber wir empfehlen, ihn einfach zu halten, da du ihn nicht ändern kannst. Wir erlauben NICHT die Existenz mehrerer Connectors mit demselben target und derselben Plattform. Andererseits kannst du soziale Connectors für verschiedene Plattformen mit demselben target haben. Zum Beispiel, wenn Benutzer sich über WeChat auf ihrem Telefon anmelden möchten, ist eine native WeChat-App gemäß den Nutzungsbedingungen von WeChat erforderlich; gleichzeitig wird eine Web-WeChat-App benötigt, um die Anmeldung bei Webanwendungen zu ermöglichen. Diese beiden WeChat-Apps teilen denselben Identitätsanbieter und sollten dasselbe Ziel haben.

Wir haben verschiedene Anwendungsfälle und Vorschläge für Benutzer zusammengefasst, da target ein kompliziertes Konzept ist.

	Beispiel	Szenario	Ergebnis	Empfohlen?
Verschiedene IdPs und unterschiedliche targets	1. GitHub Connector (target: github) 2. Google Connector (target: google)	Eine App, die sowohl die Anmeldung mit GitHub- als auch Google-Konto unterstützt.	Häufigste Anwendungsfälle.	✅
Verschiedene IdPs und dasselbe target	1. GitHub Connector (target: github) 2. Google Connector (target: github)	N/A	Es ist möglich, dass sich ein Benutzer bei einem Logto-Konto anmeldet, das mit dem GitHub-Konto eines anderen Benutzers erstellt wurde.	❌
Derselbe IdP und unterschiedliche targets	1. GitHub Connector (target: github) 2. OAuth GitHub Connector (target: github_oauth)	Der GitHub-Connector wird für Anwendung A verwendet, während der OAuth GitHub-Connector speziell für Anwendung B erstellt wurde.	Die Anmeldung bei Logto mit diesen beiden verschiedenen Connectors wird immer separate Logto-Konten erstellen - selbst wenn der Benutzer dasselbe GitHub-Konto verwendet.	Die Aufteilung deines Benutzerpools ist das einzige Szenario, in dem du beide Connectors verwenden müsstest. Es wird jedoch allgemein als Best Practice angesehen, zwei separate Mandanten zu erstellen, um diesen Anwendungsfall zu behandeln.
Derselbe IdP und dasselbe target	1. GitHub Connector (target: github) 2. OAuth GitHub Connector (target: github)	N/A	Die Verwendung eines dieser beiden Connectors kann zum exakt gleichen Ergebnis führen.	Das Erstellen von zwei Connectors, die im Wesentlichen dasselbe tun, kann für Endbenutzer verwirrend sein und ergibt wenig Sinn. Es ist besser, einen Connector zu verwenden, der deinem spezifischen Anwendungsfall entspricht.

type

type ist die Eigenschaft, die den Typ des Connectors aufzeichnet.

Wir definieren die Connectors in drei verschiedene Typen, basierend auf ihren Funktionen:

• Social: Connectors, die mit der Autorisierung der Endbenutzer auf Informationen von beliebigen Drittanbieter-Social-Media zugreifen können.
• SMS: Connectors ermöglichen es Endbenutzern, Textnachrichten auf ihren Telefonen zu empfangen.
• Email: Connectors, die beim Senden von E-Mails an Endbenutzer helfen können.

platform

platform wird verwendet, um zu identifizieren, für welche Plattform der Connector entwickelt wurde.

platform sollte entweder null oder einer der folgenden string-typisierten Werte sein:

• Native: Connectors, die NUR für native mobile Apps funktionieren.
• Web: Connectors, die NUR auf Desktop-Webanwendungen funktionieren.
• Universal: Connectors, die sowohl auf mobilen Web-Apps als auch auf Desktop-Web-Apps funktionieren können.

hinweis

platform von Email-Connectors und SMS-Connectors sollte immer null sein.
NUR Social-Connectors können nicht-NULL platform-Werte haben.

name

name ist ein Objekt, dessen Schlüssel i18n-Ländercodes und Werte die Anzeigenamen der Connectors sind.

description

description ist ebenfalls ein Objekt, dessen Schlüssel i18n-Ländercodes und Werte kurze Connector-Beschreibungen sind.

hinweis

Um die i18n-Anzeige auf der Client-Seite zu unterstützen, speichern wir die name (sowie description) Eigenschaften als eine Karte, die Ländercodes als Schlüssel und Namen (oder Beschreibungen) in lokalen Zeichen als Wert verwendet.

logo

logo ist eine URL oder ein relativer Pfad des Logos des Connectors.

logoDark

logoDark ist eine nullable URL oder ein relativer Pfad des Logos des Connectors im Dunkelmodus.

hinweis

logo ist immer erforderlich, und logoDark ist optional.

Wir zeigen logo im Hellmodus und logoDark im Dunkelmodus an, wenn es existiert. Andernfalls wird logo im Dunkelmodus angezeigt.

isStandard

isStandard ist ein OPTIONALER boolescher Attribut, um zu identifizieren, ob der soziale Connector ein "Standard"-Connector ist. Du kannst einen "Standard"-Connector an seinem wahrheitsgemäßen isStandard-Attribut erkennen.

hinweis

Logto unterstützt nur "Standard"-Social-Connectors. Das heißt, alle Logto-Email- oder SMS-Connectors sind KEINE "Standard"-Connectors.

Logto nennt Connectors, die auf offenen und standardisierten Protokollen (z. B. OAuth, OIDC, SAML usw.) basieren, "Standard"-Connectors. Es wird erwartet, dass Logto-Benutzer mehrere Instanzen auf jedem Standard-Connector basierend auf diesem Kontext erstellen. Zum Beispiel, wenn Logto bereits einen OAuth-Standard-Connector bereitgestellt hat, können Benutzer "OAuth GitHub Connector", "OAuth Google Connector" und "OAuth Facebook Connector" Instanzen erstellen. Sie basieren alle auf dem Logto OAuth-Standard-Connector.

Wenn du mit dem Connector-Design von Logto vertraut bist, kann gleichzeitig höchstens EIN Email- oder SMS-Connector existieren, was bedeutet, dass Logto derzeit keine "Standard"-Email- oder SMS-Connectors benötigt.

readme

readme ist ein relativer Pfad der README-Markdown-Datei des Connectors, deren Inhalte während der Einrichtung der Connectors im "Admin Console" angezeigt werden.

configTemplate

configTemplate ist ein relativer Pfad des Konfigurationsbeispiels des Connectors.

Remote-Speicher des Connectors: Connector DB

id

id, das als Primärschlüssel der Connector-DB fungiert, ist ein zufällig generierter string-typisierter Schlüssel, um den Connector in der DB zu identifizieren.

connectorId

connectorId ist ein string-typisierter Schlüssel und die EINZIGE Verbindung, um Connector DB und ConnectorMetadata abzugleichen. Für jedes passende Connector-DB-Daten- und Connector-Code-Modul-Paar entspricht connectorId immer metadata.id des Code-Moduls.

metadata

metadata ist ein Teil von ConnectorMetadata, das konfigurierbare Attribute enthält, d. h. logo, logoDark, target und name.

syncProfile

syncProfile ist ein boolescher Wert, um das Aktualisierungsschema des Benutzerprofils zu bestimmen, standardmäßig FALSE.

Wenn syncProfile FALSE ist, werden die Basisinformationen des Logto-Benutzers (einschließlich Name und Avatar) nur aktualisiert, wenn sich der Benutzer zum ersten Mal über diesen Connector bei Logto anmeldet. Andernfalls wird jedes Mal, wenn sich Benutzer über den Connector bei Logto anmelden, das Logto-Kontoprofil aktualisiert.

config

config könnte ein beliebiges nicht-leeres Objekt sein.

Es ist der Ort, an dem ein Connector seine Konfiguration speichert. Jeder Connector hat unterschiedliche Eigenschaften in config und es ist verpflichtet, gültig zu sein (Connectors haben unterschiedliche Standards für "gültig"), bevor es in der DB gespeichert wird. NUR diejenigen config, die die Gültigkeitsprüfung bestehen, können in die DB aktualisiert werden, andernfalls wird ein Fehler ausgelöst.

Entwickler sind verpflichtet, einen config-Schutz zu implementieren, wenn sie ihre eigenen Connectors entwickeln. Siehe Entwickle deinen Connector für weitere Details.

Möchtest du einen Blick auf config-Beispiele werfen? Gehe zu Connectors oder zur Einstellungsseite jedes Connectors.

hinweis

In der aktuellen Logto-Version kann gleichzeitig nur ein Email/SMS-Connector existieren, alle anderen Connectors desselben Typs werden automatisch gelöscht.

Die Regel, einzigartiger funktionierender Email- oder SMS-Connector, gilt nicht für Social-Connectors.
Mit anderen Worten, du kannst mehrere Social-Connectors hinzufügen.

createdAt

createdAt ist ein automatisch generierter Zeitstempel-String, um die Zeit zu verfolgen, wann ein Connector in der DB erstellt wurde.