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 Nutzern, das Verwalten zahlreicher Konten und Passwörter zu vermeiden.

Folge unseren Connector-Anleitungen, wenn du einen bestehenden Connector einrichten möchtest. Falls du den gewünschten Connector nicht findest, kannst du eigene Connectoren entwickeln, indem du den Leitfäden unter Entwickle deinen Connector folgst.

Zusammensetzung

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 Datenbank und den Rest lokal.

• Lokaler Speicher, auch bekannt als ConnectorMetadata, ist ein Objekt mit festen Eigenschaften wie Logo, Connector-Typ usw. (:face_with_monocle: Schwierigkeiten beim Verständnis dieser Eigenschaften? Keine Sorge, eine detaillierte Erklärung folgt später!)
• Remote-Speicher wird in der Datenbank gespeichert, da diese Daten relativ häufig geändert werden.

Lokaler Speicher des Connectors: ConnectorMetadata

id

id ist ein eindeutiger Schlüssel vom Typ String, um einen Connector in Logto zu identifizieren.

Er wird von den Entwicklern jedes Connectors vergeben und in die Datenbank hochgeladen.

target (Name des Identitätsanbieters)

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

Logto-Benutzer können diese Variable als „Name des Identitätsanbieters“ 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. Es ist NICHT erlaubt, mehrere Connectoren mit demselben target und derselben Plattform zu haben. Andererseits kannst du Social Connectors für verschiedene Plattformen mit demselben target haben. Zum Beispiel: Wenn Benutzer sich über WeChat auf ihrem Handy anmelden möchten, ist laut WeChat TOU eine native WeChat-App erforderlich; gleichzeitig wird eine Web-WeChat-App benötigt, um die Anmeldung in Webanwendungen zu ermöglichen. Diese beiden WeChat-Apps teilen denselben Identitätsanbieter und sollten dasselbe Target haben.

Wir haben verschiedene Anwendungsfälle und Empfehlungen für Benutzer zusammengefasst, da target ein komplexes Konzept ist.

	Beispiel	Szenario	Ergebnis	Empfohlen?
Verschiedene IdPs und verschiedene targets	1. GitHub Connector (target: github) 2. Google Connector (target: google)	Eine App, die sowohl die Anmeldung mit GitHub als auch mit Google-Konto unterstützt.	Häufigster Anwendungsfall.	✅
Verschiedene IdPs und gleiches 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.	❌
Gleicher IdP und verschiedene 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 über diese beiden verschiedenen Connectoren erstellt immer separate Logto-Konten – auch wenn der Benutzer dasselbe GitHub-Konto verwendet.	Die Aufteilung deines Benutzerpools ist das einzige Szenario, in dem du beide Connectoren benötigst. Es gilt jedoch als Best Practice, zwei separate Mandanten für diesen Anwendungsfall zu erstellen.
Gleicher IdP und gleiches target	1. GitHub Connector (target: github) 2. OAuth GitHub Connector (target: github)	N/A	Die Verwendung eines dieser beiden Connectoren kann zum exakt gleichen Ergebnis führen.	Zwei Connectoren zu erstellen, die im Grunde dasselbe tun, kann für Endbenutzer verwirrend sein und macht wenig Sinn. Es ist besser, einen Connector zu verwenden, der zu deinem Anwendungsfall passt.

type

type ist die Eigenschaft, die den Typ des Connectors festhält.

Wir definieren Connectoren anhand ihrer Funktionalität in drei verschiedene Typen:

• Social: Connectoren, die mit Zustimmung des Endbenutzers auf Informationen von Drittanbieter-Social-Media zugreifen können.
• SMS: Connectoren, die es Endbenutzern ermöglichen, Textnachrichten auf ihrem Handy zu empfangen.
• Email: Connectoren, die beim Versenden von E-Mails an Endbenutzer helfen.

platform

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

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

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

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 Connectoren 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 Map, die Ländercodes als Schlüssel und Namen (bzw. Beschreibung) in lokalen Zeichen als Wert verwendet.

logo

logo ist eine URL oder ein relativer Pfad zum Logo des Connectors.

logoDark

logoDark ist eine nullable URL oder ein relativer Pfad zum Logo des Connectors im Dark Mode.

hinweis:

logo ist immer erforderlich, logoDark ist optional.

Wir zeigen logo im Light Mode und logoDark im Dark Mode an, falls vorhanden. Andernfalls wird logo auch im Dark Mode angezeigt.

isStandard

isStandard ist ein OPTIONALS boolesches Attribut, um zu kennzeichnen, ob der Social Connector ein „Standard“-Connector ist. Du erkennst einen „Standard“-Connector an seinem wahrheitswertigen isStandard-Attribut.

hinweis:

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

Logto bezeichnet Connectoren, die auf offenen und standardisierten Protokollen (z. B. OAuth, OIDC, SAML usw.) basieren, als „Standard“-Connectors. Logto-Benutzer können auf jedem Standard-Connector mehrere Instanzen erstellen. Zum Beispiel: Wenn Logto bereits einen OAuth-Standard-Connector bereitstellt, können Benutzer Instanzen wie „OAuth GitHub Connector“, „OAuth Google Connector“ und „OAuth Facebook Connector“ erstellen. Sie basieren alle auf dem Logto OAuth-Standard-Connector.

Wenn du mit dem Connector-Design von Logto vertraut bist: Es kann maximal EIN Email- oder SMS-Connector gleichzeitig existieren, was bedeutet, dass Logto derzeit keine „Standard“-Email- oder SMS-Connectors benötigt.

readme

readme ist ein relativer Pfad zur README-Markdown-Datei des Connectors, deren Inhalt im „Admin Console“ während der Connector-Einrichtung angezeigt wird.

configTemplate

configTemplate ist ein relativer Pfad zu einem Konfigurationsbeispiel des Connectors.

Remote-Speicher des Connectors: Connector DB {#connectors-remote-storage-connector-db}

id

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

connectorId

connectorId ist ein String-Schlüssel und die EINZIGE Brücke, 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 eine Teilmenge von ConnectorMetadata, die konfigurierbare Attribute wie logo, logoDark, target und name enthält.

syncProfile

syncProfile ist ein boolescher Wert, der das Aktualisierungsschema des Benutzerprofils bestimmt, standardmäßig FALSE.

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

config

config kann ein beliebiges nicht-leeres Objekt sein.

Hier speichert ein Connector seine Konfiguration. Jeder Connector hat unterschiedliche Eigenschaften in config und sie muss gültig sein (Connectoren haben unterschiedliche Standards für „gültig“), bevor sie in der Datenbank gespeichert werden kann. NUR config, die die Gültigkeitsprüfung bestehen, können in die Datenbank übernommen werden, andernfalls wird ein Fehler ausgelöst.

Entwickler sind verpflichtet, beim Entwickeln eigener Connectoren einen config-Guard zu implementieren. Siehe Entwickle deinen Connector für weitere Details.

Du möchtest config-Beispiele sehen? Gehe zu Connectors oder zur Einstellungsseite des jeweiligen Connectors.

hinweis:

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

Die Regel, dass nur ein funktionierender Email- oder SMS-Connector existieren darf, 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 den Zeitpunkt zu verfolgen, an dem ein Connector in der Datenbank erstellt wurde.