Soziale Anmeldung mit GitHub über GitHub App einrichten

Integriere die GitHub App, um „Anmelden mit GitHub“, Kontoverknüpfung und sicheren Zugriff auf GitHub APIs mit fein abgestuften Berechtigungen und Auffrischungstokens 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.

GitHub App vs OAuth App

GitHub bietet zwei Arten von Apps für Authentifizierung und API-Zugriff: GitHub Apps und OAuth Apps. Hier ist ein Vergleich, der dir bei der Auswahl hilft:

Funktion	GitHub App	OAuth App
Berechtigungen	Fein abgestufte Berechtigungen — Zugriff nur auf bestimmte Ressourcen	Breite Berechtigungen — gewährt oft mehr Zugriff als nötig
Berechtigungsverwaltung	Nur im GitHub-Dashboard konfigurierbar; das Scope-Feld in Logto kann leer bleiben	Über Berechtigungen im Logto Connector konfiguriert
Auffrischungstokens	Werden immer während des OAuth-Flows ausgegeben	Nicht unterstützt — Tokens laufen nie ab, außer sie werden widerrufen
Token-Ablauf	Zugangstokens laufen nach 8 Stunden ab; Auffrischungstokens sind 6 Monate gültig	Zugangstokens laufen nie ab
Benutzerkontrolle	Benutzer können auswählen, auf welche Repositories die App zugreifen darf	Zugriff auf alle Repositories, auf die der Benutzer Zugriff hat
Ratenlimits	Höhere Ratenlimits, die mit Installationen skalieren	Niedrigere Ratenlimits (5.000 Anfragen/Stunde pro Benutzer)
Installation	Auf Konten/Organisationen mit granularen Repository-Zugriffsrechten installiert	Von Benutzern mit breitem Zugriff autorisiert
Webhooks	Zentrale Webhook-Unterstützung integriert	Muss für jedes Repository separat konfiguriert werden
Eigenständiges Handeln	Kann im eigenen Namen agieren (Server-zu-Server)	Agiert immer im Namen eines Benutzers

Wann solltest du die GitHub App verwenden:

• Du benötigst fein abgestufte Kontrolle über Berechtigungen und Repository-Zugriff
• Du möchtest Auffrischungstokens für langfristigen API-Zugriff mit erhöhter Sicherheit
• Du benötigst höhere API-Ratenlimits
• Du möchtest automatisierte Aufgaben unabhängig von Benutzersitzungen ausführen

Wann solltest du die OAuth App verwenden:

• Einfache Anmeldeintegration mit minimalem API-Zugriff
• Du benötigst Tokens, die nicht ablaufen (für Legacy-Integrationen)
• Du musst auf Enterprise-Ressourcen zugreifen (GitHub Apps unterstützen derzeit noch keine Enterprise-Berechtigungen)

tipp:

GitHub empfiehlt GitHub Apps gegenüber OAuth Apps für die meisten Anwendungsfälle aufgrund ihrer verbesserten Sicherheitsfunktionen und fein abgestuften Berechtigungen. Erfahre mehr über die Unterschiede zwischen GitHub Apps und OAuth Apps.

Erste Schritte

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

• „Anmelden mit GitHub“-Authentifizierung hinzufügen kann
• Benutzerkonten mit GitHub-Identitäten verknüpfen kann
• Benutzerprofilinformationen von GitHub synchronisieren kann
• Auf GitHub APIs über sichere Token-Speicherung im Logto Secret Vault für Automatisierungsaufgaben zugreifen kann (z. B. Erstellen von GitHub-Issues, Verwalten von Repositories aus deiner App)
• Auffrischungstokens verwenden kann (werden von GitHub Apps immer ausgegeben), um langfristigen API-Zugriff zu ermöglichen, ohne dass Benutzer sich erneut authentifizieren müssen

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 App, klicke auf Weiter und folge dem Schritt-für-Schritt-Tutorial, um die Integration abzuschließen.

Schritt 1: Erstelle eine GitHub App

Bevor du GitHub als Authentifizierungsanbieter verwenden kannst, musst du eine GitHub 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 > GitHub Apps.
3. Klicke auf Neue GitHub App, um eine neue Anwendung zu registrieren:
   • Name der GitHub App: Gib einen eindeutigen Namen für deine App ein. Der Name darf nicht länger als 34 Zeichen sein und muss auf GitHub eindeutig sein.
   • Homepage-URL: Gib die Homepage-URL deiner Anwendung ein.
   • Callback-URL: Kopiere die Callback-URI aus deinem Logto GitHub Connector und füge sie hier ein. Du kannst bei Bedarf mehrere Callback-URLs hinzufügen. Nachdem sich Benutzer mit GitHub angemeldet haben, werden sie hierher mit einem Autorisierungscode weitergeleitet, den Logto zur Vervollständigung der Authentifizierung verwendet.
   • Benutzerauthorisierungstokens ablaufen lassen: Lasse dies aktiviert (empfohlen). Dies ermöglicht das Ablaufen von Tokens und Auffrischungstokens für erhöhte Sicherheit.
   • Benutzerauthorisierung (OAuth) während der Installation anfordern: Optional aktivieren, um Benutzer während der Installation zur Autorisierung deiner App aufzufordern.
   • Webhook: Deaktiviere Aktiv, wenn du keine Webhook-Ereignisse benötigst. Für reine Authentifizierungsfälle sind Webhooks in der Regel nicht erforderlich.
4. Unter Berechtigungen konfiguriere die Berechtigungen, die deine App benötigt (siehe Schritt 2 unten für Details).
5. Unter Wo kann diese GitHub App installiert werden? wähle Beliebiges Konto, wenn Benutzer aus jedem GitHub-Konto deine App zur Authentifizierung verwenden dürfen.
6. Klicke auf GitHub App erstellen, um die GitHub App zu erstellen.

hinweis:

Im Gegensatz zu OAuth Apps verwenden GitHub Apps fein abgestufte Berechtigungen anstelle von weit gefassten Berechtigungen (Scopes). Du konfigurierst die Berechtigungen im GitHub-Dashboard während der App-Erstellung, und Benutzer gewähren Zugriff auf bestimmte Repositories während der Autorisierung.

Weitere Informationen zur Einrichtung von GitHub Apps findest du unter Registrieren einer GitHub App.

Schritt 2: Berechtigungen in GitHub konfigurieren

GitHub Apps verwenden fein abgestufte Berechtigungen anstelle von OAuth-Berechtigungen (Scopes). Du musst die Berechtigungen im GitHub-Dashboard beim Erstellen oder Bearbeiten deiner GitHub App konfigurieren. Diese Berechtigungen bestimmen, auf welche Daten deine App zugreifen kann.

Verständnis der GitHub App-Berechtigungen

Berechtigungen werden in drei Typen unterteilt:

• Repository-Berechtigungen: Zugriff auf Ressourcen auf Repository-Ebene (Code, Issues, Pull Requests usw.)
• Organisationsberechtigungen: Zugriff auf Ressourcen auf Organisationsebene (Mitglieder, Teams, Projekte usw.)
• Konto-Berechtigungen: Zugriff auf Benutzerdaten (E-Mail, Profil, Follower usw.)

Für jede Berechtigung kannst du auswählen:

• Kein Zugriff: Die App kann nicht auf diese Ressource zugreifen
• Nur Lesen: Die App kann diese Ressource lesen, aber nicht ändern
• Lesen & Schreiben: Die App kann diese Ressource lesen und ändern

Empfohlene Berechtigungen für Authentifizierung

Für die grundlegende "Mit GitHub anmelden"-Funktionalität konfiguriere mindestens diese Konto-Berechtigung:

Berechtigung	Zugriffsebene	Zweck
E-Mail-Adressen	Nur Lesen	E-Mail-Adresse des Benutzers für Kontoerstellung abrufen

tipp:

GitHub Apps haben impliziten Zugriff auf das öffentliche Profil, wenn sie im Namen eines Benutzers agieren. Du musst keine explizite Berechtigung für grundlegende Profildaten wie Benutzername, Avatar und öffentliche Profil-URL anfordern.

Zusätzliche Berechtigungen für API-Zugriff

Wenn deine Anwendung Zugriff auf GitHub APIs über die Authentifizierung hinaus benötigt, füge die entsprechenden Berechtigungen im GitHub-Dashboard hinzu. Hier einige gängige Beispiele:

Berechtigungstyp	Berechtigung	Zugriffsebene	Anwendungsfall
Repository	Inhalte	Nur Lesen / Lesen & Schreiben	Zugriff auf Repository-Dateien und Code
Repository	Issues	Lesen & Schreiben	Erstellen und Verwalten von Issues
Repository	Pull Requests	Lesen & Schreiben	Erstellen und Verwalten von Pull Requests
Repository	Metadaten	Nur Lesen	Zugriff auf Repository-Metadaten (für viele Aktionen erforderlich)
Organisation	Mitglieder	Nur Lesen	Auflisten von Organisationsmitgliedern
Konto	Follower	Nur Lesen	Zugriff auf Follower und Gefolgte des Benutzers

Dies ist keine vollständige Liste — GitHub Apps unterstützen viele weitere fein abgestufte Berechtigungen. Siehe Erforderliche Berechtigungen für GitHub Apps für die vollständige Übersicht.

Wichtiger Unterschied zu OAuth Apps:

Im Gegensatz zu OAuth Apps, bei denen du Berechtigungen (Scopes) im Logto Connector konfigurierst, werden GitHub App-Berechtigungen vollständig im GitHub-Dashboard verwaltet. Du kannst das Feld Scope in deinem Logto GitHub Connector leer lassen — es ist nicht erforderlich, da GitHub Apps keine traditionellen OAuth-Berechtigungen verwenden.

Konfiguriere einfach die benötigten Berechtigungen in GitHub, und Benutzer werden während der Autorisierung zur Freigabe aufgefordert.

Schritt 3: Konfiguriere deinen Logto Connector

Nach dem Erstellen der GitHub App wirst du zur Einstellungsseite weitergeleitet, wo du die Zugangsdaten erhältst.

1. Kopiere auf der Einstellungsseite deiner GitHub App die Client-ID und füge sie in das Feld clientId in Logto ein.
2. Unter Client-Geheimnisse klicke auf Neues Client-Geheimnis generieren. Kopiere das generierte Geheimnis und füge es in das Feld clientSecret in Logto ein.
3. Klicke in Logto auf Speichern und Fertig, um dein Identitätssystem mit GitHub zu verbinden.

warnung:

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

hinweis:

Die Client-ID einer GitHub App unterscheidet sich von der App-ID. Stelle sicher, dass du die Client-ID verwendest (auf der Einstellungsseite als "Client ID" angezeigt), nicht die App-ID.

Schritt 4: Allgemeine Einstellungen

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

Profilinformationen synchronisieren

Im GitHub Connector kannst du konfigurieren, wie Profilinformationen von GitHub-Benutzerdaten in das Logto-Benutzerprofil synchronisiert werden, einschließlich name, avatar und email. Wähle aus den folgenden Optionen:

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

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), aktiviere die Token-Speicherung in Logto:

1. Konfiguriere die erforderlichen Berechtigungen in den Einstellungen deiner GitHub App (Schritt 2).
2. Aktiviere Tokens für dauerhaften API-Zugriff speichern im Logto GitHub Connector. Logto speichert sowohl das Zugangstoken als auch das Auffrischungstoken sicher im Secret Vault.

hinweis:

Da GitHub Apps immer Auffrischungstokens ausstellen, speichert Logto beide Tokens automatisch. Das Zugangstoken läuft nach 8 Stunden ab, aber Logto kann das Auffrischungstoken verwenden, um neue Zugangstokens zu erhalten und so einen unterbrechungsfreien API-Zugriff für bis zu 6 Monate sicherstellen.

Schritt 5: Teste deine Integration (Optional)

Bevor du live gehst, teste deine GitHub App-Integration:

1. Verwende den Connector in einem Logto-Entwicklungstenant.
2. Überprüfe, dass sich Benutzer mit GitHub anmelden können.
3. Prüfe, dass Benutzer während der Autorisierung nach den richtigen Berechtigungen gefragt werden.
4. Wenn du die Token-Speicherung aktiviert hast, stelle sicher, dass Zugangstokens (und Auffrischungstokens) korrekt gespeichert werden.
5. Teste API-Aufrufe mit den gespeicherten Tokens, um sicherzustellen, dass die Berechtigungen wie erwartet funktionieren.

GitHub Apps funktionieren sofort mit jedem GitHub-Benutzerkonto – es sind keine Testbenutzer oder App-Freigaben wie bei anderen Plattformen erforderlich. Wenn deine App jedoch in einer Organisation installiert ist, müssen Organisationsbesitzer die Installation möglicherweise genehmigen.

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 Benutzer sich mit GitHub authentifizieren können.

Erfahre mehr über die soziale Anmeldeerfahrung.

Ein GitHub-Konto verknüpfen oder trennen

Nutze die Account API, um ein individuelles Account Center in deiner App zu erstellen, das angemeldeten Benutzern ermöglicht, ihr GitHub-Konto zu verknüpfen oder zu trennen. Folge dem Account API Tutorial

tipp:

Es ist erlaubt, den GitHub Connector nur 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-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.

Da GitHub Apps während des OAuth-Flows immer Auffrischungstokens ausgeben, speichert Logto sowohl Zugangstokens als auch Auffrischungstokens. Zugangstokens laufen nach 8 Stunden ab, aber Logto verwendet automatisch das Auffrischungstoken (6 Monate gültig), um neue Zugangstokens zu erhalten und so einen unterbrechungsfreien API-Zugriff zu gewährleisten.

GitHub-Identität des 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 gewährten und synchronisierten Profilinformationen aus dem GitHub-Konto einsehen sowie den Status von Zugangstoken und Auffrischungstoken überprüfen.

hinweis:

Im Gegensatz zu OAuth Apps, die Berechtigungen verwenden, nutzen GitHub Apps fein abgestufte Berechtigungen, die im GitHub-Dashboard konfiguriert werden. Das Benutzer-Zugangstoken ist auf die Berechtigungen beschränkt, die sowohl deine App als auch der Benutzer haben. Logto kann die Liste der Berechtigungen nicht direkt anzeigen, aber deine Anwendung erhält Zugriff basierend auf den in deinen GitHub App-Einstellungen konfigurierten Berechtigungen.

Referenzen

GitHub Entwicklerdokumentation – Über GitHub Apps

GitHub Entwicklerdokumentation – GitHub App registrieren

GitHub Entwicklerdokumentation – Benutzer-Zugangstokens generieren

GitHub Entwicklerdokumentation – Benutzer-Zugangstokens auffrischen

GitHub Apps vs OAuth Apps