Zum Hauptinhalt springen

Schritt-für-Schritt-Anleitung zur Entwicklung eines Social Connectors

Der schnellste Weg, um loszulegen, ist, den Code eines bestehenden offiziellen Connectors zu kopieren und ihn an deine Bedürfnisse anzupassen. Nehmen wir den GitHub-Connector als Beispiel.

Schritt 1: Klone ein bestehendes Connector-Paket​

In einem Connector-Quellordner findest du folgende Dateien:

  • index.ts: Die Haupteinstiegsdatei des Connectors.
  • constant.ts: Die im Connector verwendeten Konstanten.
  • types.ts: Die im Connector verwendeten TypeScript-Typen.
  • index.test.ts: Die Testfälle für den Connector.
  • mock.ts: Die in den Connector-Testfällen verwendeten Mock-Daten.

Neben diesen Dateien solltest du auch eine README.md-Datei bereitstellen, um den Connector zu beschreiben, ein logo.svg (optional ein logo-dark.svg für eine bessere Dark-Mode-Benutzererfahrung) und eine package.json-Datei, um die npm-Paketinformationen zu definieren.

Schritt 2: Passe die Haupteinstiegsdatei (index.ts) an​

In der Datei index.ts findest du den Großteil der Connector-Logik. Es gibt typischerweise 4 Funktionen, die du implementieren musst:

  • getAuthorizationUri: Generiert die Autorisierungs-URI für die Drittanbieter-Social-Plattform. Für GitHub wäre das: https://github.com/login/oauth/authorize?client_id={clientId}&redirect_uri={redirectUri}&state={state}. Siehe die Entwicklerdokumentation deiner Zielplattform, um die korrekte URI zu erhalten.
  • authorizationCallbackHandler: Überprüft die zurückgegebenen Parameterwerte in der Autorisierungs-Callback-URI, extrahiert den Autorisierungscode (code) und behandelt mögliche Fehler.
  • getAccessToken: Tauscht den Autorisierungscode (code) gegen ein Zugangstoken (Access token) aus.
  • getUserInfo: Ruft mit dem Zugangstoken (Access token) Benutzerinformationen von der Drittanbieter-Social-Plattform ab.

Die meisten anderen allgemeinen Logiken werden bereits im Logto Connector Kit abgedeckt, was dir die Arbeit erleichtern sollte.

Am Ende der Datei musst du nur noch das Connector-Objekt exportieren, und zwar nach derselben Code-Struktur wie beim GitHub-Connector.

const createGithubConnector: CreateConnector<SocialConnector> = async ({ getConfig }) => {
  return {
    metadata: defaultMetadata,
    type: ConnectorType.Social,
    configGuard: githubConfigGuard,
    getAuthorizationUri: getAuthorizationUri(getConfig),
    getUserInfo: getUserInfo(getConfig),
  };
};

Schritt 3: Teste den Connector​

Unit-Test​

Schreibe zunächst einige Unit-Testfälle und stelle sicher, dass die Grundfunktionen wie erwartet funktionieren.

Lokaler Test​

  • Richte Logto in deiner lokalen Umgebung ein: Logto bietet mehrere Möglichkeiten, lokal zu laufen – du kannst entweder die CLI, Docker oder sogar den Build aus dem Quellcode verwenden. Siehe die Dokumentation für weitere Details.
  • Verknüpfe deinen benutzerdefinierten Connector mit deiner Logto-Instanz: Verwende die CLI, um einen symbolischen Link deines Connectors zur Logto-Instanz zu erstellen. Weitere Details. 
    cd logto
    npx @logto/cli connector link -p .
  • Nach dem Verknüpfen solltest du den Connector im Ordner <logto-root-path>/packages/core/connectors sehen.
  • Starte deine Logto-Instanz neu, gehe zur Logto Admin Console, und du solltest ihn in der Liste der Social Connectors sehen.
  • Konfiguriere deinen Connector in Konsole > Anmeldung & Konto > Anmeldung und Registrierung > Soziale Anmeldung. Probiere ihn in unserer Demo-App mit der Funktion „Live-Vorschau“ aus.