Zum Hauptinhalt springen

Soziale Anmeldung mit GitHub einrichten (Set up social login with GitHub)

Integriere die GitHub OAuth app, um „Anmelden mit GitHub“, Kontoverknüpfung und sicheren Zugriff auf GitHub APIs zu ermöglichen.

tipp:

Diese Anleitung setzt voraus, dass du ein grundlegendes Verständnis von Logto Connectors hast. Für diejenigen, die damit nicht vertraut sind, verweisen wir auf die Connectors Anleitung, um loszulegen.

Erste Schritte​

Der GitHub Connector ermöglicht die OAuth 2.0-Integration, damit deine Anwendung:

  • „Anmelden mit GitHub“-Authentifizierung hinzufügt
  • Benutzerkonten mit GitHub-Identitäten verknüpft
  • Benutzerprofilinformationen von GitHub synchronisiert
  • Auf GitHub APIs über sichere Token-Speicherung im Logto Secret Vault für Automatisierungsaufgaben zugreift (z. B. Erstellen von GitHub-Issues, Verwalten von Repositories aus deiner App)

Um diese Authentifizierungsfunktionen einzurichten, erstelle zuerst einen GitHub Connector in Logto:

  1. Gehe zu Logto-Konsole > Connector > Social Connector.
  2. Klicke auf Sozialen Connector hinzufügen, wähle GitHub, klicke auf Weiter und folge dem Schritt-für-Schritt-Tutorial, um die Integration abzuschließen.

Schritt 1: Erstelle eine OAuth-App auf GitHub​

Bevor du GitHub als Authentifizierungsanbieter verwenden kannst, musst du eine OAuth-App auf GitHub erstellen, um OAuth 2.0-Zugangsdaten zu erhalten.

  1. Gehe zu GitHub und melde dich mit deinem Konto an oder erstelle ein neues Konto, falls erforderlich.
  2. Navigiere zu Einstellungen > Entwicklereinstellungen > OAuth-Apps.
  3. Klicke auf Neue OAuth-App, um eine neue Anwendung zu registrieren:
    • Anwendungsname: Gib einen aussagekräftigen Namen für deine App ein.
    • Homepage-URL: Gib die Homepage-URL deiner Anwendung ein.
    • Autorisierungs-Callback-URL: Kopiere die Callback-URI aus deinem Logto GitHub Connector und füge sie hier ein. Nachdem sich Benutzer mit GitHub angemeldet haben, werden sie hierher mit einem Autorisierungscode weitergeleitet, den Logto zur Vervollständigung der Authentifizierung verwendet.
    • Anwendungsbeschreibung: (Optional) Füge eine kurze Beschreibung deiner App hinzu.
  4. Klicke auf Anwendung registrieren, um die OAuth-App zu erstellen.
hinweis:

Wir empfehlen, das Kontrollkästchen Device Flow aktivieren nicht zu markieren, da Benutzer, die sich mit GitHub auf mobilen Geräten anmelden, die anfängliche Anmeldeaktion in der GitHub Mobile App bestätigen müssten. Viele GitHub-Nutzer installieren die GitHub Mobile App nicht auf ihren Handys, was den Anmeldevorgang blockieren könnte. Aktiviere dies nur, wenn du erwartest, dass Endbenutzer ihren Anmeldevorgang über die GitHub Mobile App bestätigen. Siehe Details zum Device Flow.

Weitere Details zum Einrichten von GitHub OAuth-Apps findest du unter Erstellen einer OAuth-App.

Schritt 2: Konfiguriere deinen Logto Connector​

Nachdem du die OAuth-App in GitHub erstellt hast, wirst du auf eine Detailseite weitergeleitet, auf der du die Client-ID kopieren und ein Client-Geheimnis generieren kannst.

  1. Kopiere die Client-ID aus deiner GitHub OAuth-App und füge sie in das Feld clientId in Logto ein.
  2. Klicke in GitHub auf Neues Client-Geheimnis generieren, um ein neues Geheimnis zu erstellen, und kopiere es dann in das Feld clientSecret in Logto.
  3. Klicke in Logto auf Speichern und Fertig, um dein Identitätssystem mit GitHub zu verbinden.
warnung:

Halte dein Client-Geheimnis sicher und gib es niemals im Client-seitigen Code preis. GitHub-Client-Geheimnisse können nicht wiederhergestellt werden, falls sie verloren gehen – du musst ein neues generieren.

Schritt 3: Berechtigungen (Scopes) konfigurieren (Optional)​

Berechtigungen (Scopes) definieren, welche Zugriffsrechte deine App von den Benutzern anfordert und steuern, auf welche Daten deine App in deren GitHub-Konten zugreifen kann.

Verwende das Feld Scopes in Logto, um zusätzliche Berechtigungen von GitHub anzufordern. Wähle je nach Bedarf eine der folgenden Vorgehensweisen:

Option 1: Keine zusätzlichen API-Berechtigungen benötigt​

  • Lasse das Feld Scopes in deinem Logto GitHub Connector leer.
  • Die Standardberechtigung read:user wird angefordert, damit Logto grundlegende Benutzerinformationen (z. B. E-Mail, Name, Avatar) korrekt abrufen kann.

Option 2: Zusätzliche Berechtigungen beim Anmelden anfordern​

  • Durchsuche alle verfügbaren GitHub-Berechtigungen für OAuth-Apps und füge nur die Berechtigungen hinzu, die deine App benötigt.
  • Gib alle gewünschten Berechtigungen im Feld Scopes ein, getrennt durch Leerzeichen.
  • Alle hier aufgeführten Berechtigungen überschreiben die Standardwerte, daher immer die Authentifizierungsberechtigung read:user einschließen.
  • Häufig verwendete zusätzliche Berechtigungen sind:
    • repo: Vollständige Kontrolle über private Repositories
    • public_repo: Zugriff auf öffentliche Repositories
    • user:email: Zugriff auf Benutzer-E-Mail-Adressen
    • notifications: Zugriff auf Benachrichtigungen
  • Stelle sicher, dass alle Berechtigungen korrekt geschrieben und gültig sind. Eine falsche oder nicht unterstützte Berechtigung führt zu einem "Invalid scope"-Fehler von GitHub.

Option 3: Schrittweise Berechtigungen später anfordern​

  • Nachdem sich der Benutzer angemeldet hat, kannst du bei Bedarf zusätzliche Berechtigungen anfordern, indem du einen föderierten sozialen Autorisierungsfluss erneut startest und das gespeicherte Token-Set des Benutzers aktualisierst.
  • Diese zusätzlichen Berechtigungen müssen nicht im Feld Scopes deines Logto GitHub Connectors eingetragen werden und können über die Social Verification API von Logto erreicht werden.

Wenn du diese Schritte befolgst, fordert dein Logto GitHub Connector genau die Berechtigungen an, die deine App benötigt – nicht mehr und nicht weniger.

tipp:

Wenn deine App diese Berechtigungen anfordert, um auf die GitHub API zuzugreifen und Aktionen auszuführen, stelle sicher, dass du Tokens für dauerhaften API-Zugriff speichern im Logto GitHub Connector aktivierst. Siehe den nächsten Abschnitt für Details.

Schritt 4: Allgemeine Einstellungen​

Hier sind einige allgemeine Einstellungen, die die Verbindung zu GitHub nicht blockieren, aber das Authentifizierungserlebnis für Endbenutzer beeinflussen können.

Profilinformationen synchronisieren​

Im GitHub Connector kannst du die Richtlinie für das Synchronisieren von Profilinformationen wie Benutzernamen und Avataren festlegen. Wähle aus:

  • Nur bei Registrierung synchronisieren: Profilinformationen werden einmalig abgerufen, wenn sich der Benutzer zum ersten Mal anmeldet.
  • Immer bei Anmeldung synchronisieren: Profilinformationen werden jedes Mal aktualisiert, wenn sich der Benutzer anmeldet.

Tokens speichern, um auf GitHub APIs zuzugreifen (Optional)​

Wenn du auf GitHub APIs zugreifen und Aktionen mit Benutzerautorisierung durchführen möchtest (entweder über soziale Anmeldung oder Kontoverknüpfung), muss Logto bestimmte API-Berechtigungen erhalten und Tokens speichern.

  1. Füge die erforderlichen Berechtigungen gemäß den obigen Anweisungen hinzu.
  2. Aktiviere Tokens für dauerhaften API-Zugriff speichern im Logto GitHub Connector. Logto speichert GitHub Zugangstokens sicher im Secret Vault.
hinweis:

Wenn du eine GitHub OAuth-App wie in diesem Tutorial beschrieben verwendest, kannst du kein Auffrischungstoken von GitHub erhalten, da dessen Zugangstoken nicht abläuft, es sei denn, der Benutzer widerruft es manuell. Daher musst du offline_access nicht im Feld Scopes hinzufügen – dies könnte sonst zu einem Fehler führen.

Wenn du möchtest, dass das Zugangstoken abläuft oder Auffrischungstokens verwenden möchtest, solltest du stattdessen eine GitHub App integrieren. Erfahre mehr über die Unterschiede zwischen GitHub Apps und OAuth Apps.

Schritt 5: Teste deine Integration (Optional)​

Bevor du live gehst, teste deine GitHub-Integration:

  1. Verwende den Connector in einem Logto-Entwicklungstenant.
  2. Überprüfe, ob sich Benutzer mit GitHub anmelden können.
  3. Prüfe, ob die richtigen Berechtigungen angefordert werden.
  4. Teste API-Aufrufe, falls du Tokens speicherst.

GitHub OAuth-Apps funktionieren sofort mit jedem GitHub-Benutzerkonto – es sind keine Testbenutzer oder App-Freigaben wie bei anderen Plattformen erforderlich.

Den GitHub Connector nutzen​

Nachdem du einen GitHub Connector erstellt und mit GitHub verbunden hast, kannst du ihn in deine Endbenutzer-Flows einbinden. Wähle die Optionen, die zu deinen Anforderungen passen:

„Anmelden mit GitHub“ aktivieren​

  1. Gehe in der Logto-Konsole zu Anmeldeerfahrung > Registrierung und Anmeldung.
  2. Füge den GitHub Connector im Abschnitt Soziale Anmeldung hinzu, damit sich Benutzer mit GitHub authentifizieren können.

Erfahre mehr über die soziale Anmeldeerfahrung.

Nutze die Account API, um ein individuelles Account Center in deiner App zu erstellen, in dem angemeldete Benutzer ihr GitHub-Konto verknüpfen oder trennen können. Folge dem Account API Tutorial

tipp:

Es ist möglich, den GitHub Connector ausschließlich für die Kontoverknüpfung und den API-Zugriff zu aktivieren, ohne ihn für die soziale Anmeldung zu aktivieren.

Auf GitHub APIs zugreifen und Aktionen ausführen​

Deine Anwendung kann gespeicherte GitHub Zugangstokens (Access tokens) aus dem Secret Vault abrufen, um GitHub APIs aufzurufen und Backend-Aufgaben zu automatisieren (z. B. Issues erstellen, Repositories verwalten oder Workflows automatisieren). Siehe die Anleitung zum Abrufen gespeicherter Tokens für den API-Zugriff.

Die GitHub-Identität eines Benutzers verwalten​

Nachdem ein Benutzer sein GitHub-Konto verknüpft hat, können Administratoren diese Verbindung in der Logto-Konsole verwalten:

  1. Navigiere zu Logto-Konsole > Benutzerverwaltung und öffne das Profil des Benutzers.
  2. Unter Soziale Verbindungen finde den GitHub-Eintrag und klicke auf Verwalten.
  3. Auf dieser Seite können Administratoren die GitHub-Verbindung des Benutzers verwalten, alle Profilinformationen einsehen, die vom GitHub-Konto gewährt und synchronisiert wurden, und den Status des Zugangstokens (Access token) überprüfen.
hinweis:

Die Access token-Antwort von GitHub enthält keine spezifischen Scope-Informationen, daher kann Logto die vom Benutzer gewährten Berechtigungen nicht direkt anzeigen. Solange der Benutzer jedoch den angeforderten Berechtigungen (Scopes) während der Autorisierung zugestimmt hat, hat deine Anwendung beim Zugriff auf die GitHub API die entsprechenden Berechtigungen.

Referenz​

GitHub Entwicklerdokumentation – Über Apps

GitHub Entwicklerdokumentation – Erstellen einer OAuth App

GitHub OAuth App Scopes Dokumentation