Best Practices beim Erstellen einer GitHub-App

Auswählen der mindestens erforderlichen Berechtigungen

Wenn du eine GitHub App registrierst, wähle die Mindestberechtigungen aus, die deine GitHub App benötigt. Wenn Schlüssel oder Token für deine App kompromittiert werden, lässt sich damit der mögliche Schaden begrenzen. Weitere Informationen zum Auswählen von Berechtigungen findest du unter Auswählen von Berechtigungen für eine GitHub-App.

Wenn deine GitHub App ein Installationszugriffstoken oder Benutzerzugriffstoken erstellt, kannst du die Repositorys, auf die die App zugreifen kann, und die Berechtigungen des Tokens weiter einschränken. Weitere Informationen finden Sie unter Generieren eines Installationszugriffstokens für eine GitHub-App und unter Generieren eines Benutzerzugriffstokens für eine GitHub-App.

Unterhalb der Ratenbegrenzung bleiben

Abonniere Webhookereignisse, anstatt die API nach Daten abzufragen. Das hilft der GitHub App dabei, innerhalb der API-Ratenbegrenzung zu bleiben. Weitere Informationen findest du unter Verwenden von Webhooks mit GitHub-Apps und unter Erstellen einer GitHub-App, die auf Webhookereignisse reagiert.

Erwäge die Verwendung von bedingten Anforderungen, um die Ratenbegrenzung einzuhalten. Weitere Informationen zu bedingten Anforderungen findest du unter Bewährte Methoden für die Verwendung der REST-API.

Wenn möglich, solltest du die Verwendung von konsolidierten GraphQL Abfragen anstelle von REST-API-Anforderungen in Betracht ziehen, damit die Ratenbegrenzungen nicht überschritten werden. Weitere Informationen findest du unter Vergleich der REST-API von GitHub und der GraphQL-API und unter Dokumentation zu GitHub GraphQL-API.

Wenn eine Ratenbegrenzung erreicht ist und du eine API-Anforderung wiederholen musst, verwende die Antwortheader x-ratelimit-reset oder Retry-After. Wenn diese Header nicht verfügbar sind, warte eine exponentiell länger werdende Zeitspanne zwischen den Wiederholungsversuchen ab und gib nach einer bestimmten Anzahl von Wiederholungsversuchen einen Fehler aus. Weitere Informationen findest du unter Bewährte Methoden für die Verwendung der REST-API.

Schützen der Anmeldeinformationen deiner App

Du kannst einen privaten Schlüssel und einen geheimen Clientschlüssel für deine GitHub App generieren. Mit diesen Anmeldeinformationen kann deine App Installationszugriffstoken, Benutzerzugriffstoken und Aktualisierungstoken generieren. Diese Token können verwendet werden, um API-Anforderungen im Namen von App-Installationen oder Benutzer*innen auszuführen.

Du musst diese Anmeldeinformationen sicher aufbewahren. Welchen Speichermechanismus du verwendest, richtet sich nach deiner Integrationsarchitektur und der Plattform, auf der die App ausgeführt wird. Im Allgemeinen solltest du einen Mechanismus verwenden, der für die Speicherung vertraulicher Daten auf der von dir verwendeten Plattform konzipiert ist.

Private Schlüssel

Der private Schlüssel für deine GitHub App gewährt Zugriff auf jedes Konto, in dem die App installiert ist.

Du solltest erwägen, den privaten Schlüssel deiner GitHub App in einem Schlüsseltresor wie Azure Key Vault zu speichern und nur zum Signieren zu verwenden.

Alternativ kannst du den Schlüssel als Umgebungsvariable speichern. Allerdings ist hierbei der Schutz schwächer als bei der Speicherung in einem Schlüsseltresor. Wenn ein Angreifer Zugriff auf die Umgebung erhält, kann er den privaten Schlüssel lesen und die dauerhafte Authentifizierung als GitHub App erlangen.

Du solltest deinen privaten Schlüssel niemals in deiner App hartcodieren, auch dann nicht, wenn dein Code in einem privaten Repository gespeichert ist. Wenn deine App ein nativer Client oder eine clientseitige App ist oder auf einem Benutzergerät ausgeführt wird (im Gegensatz zur Ausführung auf deinen Servern), solltest du deinen privaten Schlüssel niemals mit deiner App ausliefern.

Du solltest nicht mehr private Schlüssel generieren, als du benötigst. Du solltest private Schlüssel löschen, die du nicht mehr benötigst. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps.

Geheime Clientschlüssel

Geheime Clientschlüssel werden verwendet, um Benutzerzugriffstoken für deine App zu generieren, es sei denn, deine App verwendet den Gerätefluss. Weitere Informationen findest du unter Generieren eines Benutzerzugriffstokens für eine GitHub-App.

Wenn es sich bei deiner App um eine Website oder Web-App handelt, solltest du den geheimen Clientschlüssel in einem Schlüsseltresor wie Azure Key Vault oder als verschlüsselte Umgebungsvariable oder geheimen Clientschlüssel auf deinem Server speichern.

Wenn deine App ein nativer Client oder eine clientseitige App ist oder auf einem Benutzergerät ausgeführt wird (im Gegensatz zur Ausführung auf deinen Servern), kannst du deinen geheimen Clientschlüssel nicht schützen. Du solltest mit großer Vorsicht vorgehen, wenn du planst, den Zugriff auf deine eigenen Dienste basierend auf von deiner App generierten Token zu schützen, da jede Person auf den geheimen Clientschlüssel zugreifen kann, um ein Token zu generieren.

Installationszugriffstoken, Benutzerzugriffstoken und Aktualisierungstoken

Installationszugriffstoken werden verwendet, um API-Anforderungen im Namen einer App-Installation zu senden. Benutzerzugriffstoken werden verwendet, um API-Anforderungen im Namen von Benutzer*innen zu senden. Aktualisierungstoken werden verwendet, um Benutzerzugriffstoken neu zu generieren. Deine App kann ihren privaten Schlüssel verwenden, um ein Installationszugriffstoken zu generieren. Deine App kann ihren geheimen Clientschlüssel verwenden, um ein Benutzerzugriffstoken und ein Aktualisierungstoken zu generieren.

Wenn es sich bei deiner App um eine Website oder Web-App handelt, solltest du die Token in deinem Back-End verschlüsseln und sicherstellen, dass rund um die Systeme, die auf die Token zugreifen können, Sicherheit herrscht. Du solltest erwägen, Aktualisierungstoken an anderer Stelle zu speichern als aktive Zugriffstoken.

Wenn deine App ein nativer Client oder eine clientseitige App ist oder auf einem Benutzergerät ausgeführt wird (im Gegensatz zur Ausführung auf deinen Servern), kannst du Token möglicherweise nicht so gut schützen wie eine App, die auf deinen Servern ausgeführt wird. Du solltest keine Installationszugriffstoken generieren, denn dafür ist ein privater Schlüssel erforderlich. Stattdessen solltest du Benutzerzugriffstoken generieren. Du solltest Token mit dem Mechanismus speichern, der für die Plattform deiner App empfohlen wird. Denk aber daran, dass der Speichermechanismus möglicherweise nicht vollständig sicher ist.

Verwenden des geeigneten Tokentyps

GitHub Apps können Installationszugriffstoken oder Benutzerzugriffstoken generieren, um authentifizierte API-Anforderungen zu senden.

Installationszugriffstoken ordnen deiner App Aktivitäten zu. Diese sind nützlich für Automatisierungen, die unabhängig von Benutzer*innen agieren.

Benutzerzugriffstoken ordnen einer Benutzerin oder einem Benutzer und deiner App Aktivitäten zu. Diese sind nützlich, um Aktionen basierend auf Benutzereingaben oder im Namen einer Benutzerin oder eines Benutzers auszuführen.

Ein Installationszugriffstoken ist basierend auf den Berechtigungen und dem Zugriff der GitHub App eingeschränkt. Ein Benutzerzugriffstoken wird sowohl basierend auf der Berechtigung und dem Zugriff der GitHub App als auch der Berechtigung und dem Zugriff des Benutzers bzw. der Benutzerin eingeschränkt. Wenn deine GitHub App eine Aktion im Namen einer Benutzerin oder eines Benutzers ausführt, sollte sie daher immer ein Benutzerzugriffstoken anstelle eines Installationszugriffstokens verwenden. Andernfalls kann deine App es einem Benutzer oder einer Benutzerin ermöglichen, Dinge zu sehen oder zu tun, die er oder sie nicht sehen oder tun sollte.

Deine App sollte niemals ein personal access token oder ein GitHub-Kennwort für die Authentifizierung verwenden.

Autorisieren Sie gründlich und dauerhaft

Nach der Anmeldung bei einem Benutzer müssen App-Entwickler zusätzliche Schritte ausführen, um sicherzustellen, dass der Benutzer Zugriff auf die Daten in Ihrem System haben soll. Für jede Anmeldung sind neue Überprüfungen ihrer Mitgliedschaften, des Zugriffs und des aktuellen SSO-Status erforderlich.

Verwenden Sie den dauerhaften, eindeutigen `id`, um den Benutzer zu speichern.

Wenn sich ein Benutzer anmeldet und Aktionen in Ihrer Anwendung ausführt, müssen Sie sich merken, welcher Benutzer diese Aktion ausgeführt hat, um ihm beim nächsten Anmelden Zugriff auf dieselben Ressourcen zu gewähren.

Um Benutzer in Ihrer Datenbank korrekt zu speichern, verwenden Sie immer den id des Benutzers. Dieser Wert ändert sich niemals für den Benutzer oder wird verwendet, um auf einen anderen Benutzer zu verweisen, sodass sichergestellt wird, dass Sie Zugriff auf den gewünschten Benutzer gewähren. Sie können den id eines Benutzers mit dem REST-API-Endpunkt GET /user finden. Weitere Informationen finden Sie unter „REST-API-Endpunkte für Benutzer“.

Wenn Sie Verweise auf Repositorys, Organisationen und Unternehmen speichern, verwenden Sie auch ihre id, um sicherzustellen, dass Ihre Links zu ihnen korrekt bleiben.

Verwenden Sie niemals Bezeichner, die sich im Laufe der Zeit ändern können, einschließlich Benutzerhandles, Organisations-Slugs oder E-Mail-Adressen.

Überprüfen des Organisationszugriffs bei jeder neuen Authentifizierung

Wenn du ein Benutzerzugriffstoken verwendest, solltest du nachverfolgen, für welche Organisationen das Token autorisiert ist. Wenn eine Organisation SAML SSO verwendet und ein Benutzer oder eine Benutzerin SAML SSO nicht ausgeführt hat, wird das Benutzerzugriffstoken keinen Zugriff auf diese Organisation haben. Du kannst den GET /user/installations-REST-API-Endpunkt verwenden, um zu überprüfen, auf welche Organisationen ein Benutzerzugriffstoken Zugriff hat. Wenn der Benutzer nicht berechtigt ist, auf eine Organisation zuzugreifen, sollten Sie seinen Zugriff auf die Daten der Organisation innerhalb Ihrer eigenen Anwendung verhindern, bis er SAML SSO durchführt. Weitere Informationen findest du unter Rest-API-Endpunkte für GitHub App-Installationen.

Speichern von Benutzerdaten mit Organisations- und Unternehmenskontexten

Über das Nachverfolgen der Benutzeridentität über das id Feld hinaus sollten Sie Daten für die Organisation oder das Unternehmen aufbewahren, unter denen jeder Benutzer arbeitet. Dadurch wird sichergestellt, dass keine vertraulichen Informationen verloren gehen, wenn ein Benutzer die Rolle wechselt.

Zum Beispiel:

Ein Benutzer befindet sich in der Mona Organisation, für die SAML SSO erforderlich ist, und meldet sich nach dem Ausführen von SSO bei Ihrer App an. Ihre App hat nun Zugriff auf alles, was der Benutzer in Mona tut.
Der Benutzer zieht einen Haufen Code aus einem Repository in Mona und speichert ihn in Ihrer Anwendung zur Analyse.
Später wechselt der Benutzer Aufträge und wird aus der Mona Organisation entfernt.

Wenn der Benutzer auf Ihre Anwendung zugreift, kann er dann immer noch den Code und die Analysen der Mona Organisation in seinem Benutzerkonto sehen?

Aus diesem Grund ist es wichtig, die Quelle der Daten zu verfolgen, die Ihre App speichert. Andernfalls ist Ihre App eine Datenschutzbedrohung für Organisationen, und sie werden Ihre App wahrscheinlich verbieten, wenn sie nicht vertrauen können, dass Ihre App ihre Daten ordnungsgemäß schützt.

Ablauf von Token

GitHub empfiehlt dringend, ablaufende Benutzerzugriffstoken zu verwenden. Wenn du dich zuvor gegen die Verwendung von ablaufenden Benutzerzugriffstoken entschieden hast, aber dieses Feature nun aktivieren möchtest, findest du unter Aktivieren optionaler Features für GitHub-Apps weitere Informationen.

Installationszugriffstoken laufen nach einer Stunde ab, ablaufende Benutzerzugriffstoken nach acht Stunden und Aktualisierungstoken nach sechs Monaten. Du kannst Token aber auch widerrufen, sobald du sie nicht mehr benötigst. Informationen zum Widerrufen eines Installationszugriffstokens findest du unter „DELETE /installation/token„, Informationen zum Widerrufen eines Installationszugriffstokens findest du unter „DELETE /applications/{client_id}/token„.

Zwischenspeichern von Token

Benutzerzugriffstoken und Installationszugriffstoken sollen bis zu ihrem Ablauf verwendet werden. Du solltest deine erstellten Token zwischenspeichern. Bevor du ein neues Token erstellst, solltest du im Cache überprüfen, ob du bereits über ein gültiges Token verfügst. Durch die Wiederverwendung von Token wird deine App schneller, da sie weniger Anforderungen zum Generieren von Token stellt.

Erstellen eines Plans für die Behandlung von Sicherheitsverletzungen

Du solltest einen Plan vorbereiten, damit du jegliche Sicherheitsverletzungen schnellstmöglich korrigieren kannst.

Für den Fall, dass der private Schlüssel oder das Geheimnis deiner App kompromittiert wird, musst du einen neuen Schlüssel bzw. ein neues Geheimnis generieren, deine App aktualisieren, sodass sie den neuen Schlüssel bzw. das neue Geheimnis verwendet, und den alten Schlüssel bzw. das alte Geheimnis löschen.

Falls Installationszugriffstoken, Benutzerzugriffstoken oder Aktualisierungstoken kompromittiert werden, solltest du diese Token sofort widerrufen. Informationen zum Widerrufen eines Installationszugriffstokens findest du unter „DELETE /installation/token„, Informationen zum Widerrufen eines Installationszugriffstokens findest du unter „DELETE /applications/{client_id}/token„.

Regelmäßige Überprüfungen auf Sicherheitsrisiken

Du solltest regelmäßige Sicherheitsrisikoüberprüfungen für deine App durchführen. Beispielsweise kannst du die Codeüberprüfung und die Geheimnisüberprüfung für das Repository einrichten, das den Code deiner App hostet. Weitere Informationen findest du unter Informationen zu Codescans und unter Informationen zur Geheimnisüberprüfung.

Auswählen einer geeigneten Umgebung

Wenn deine App auf einem Server ausgeführt wird, vergewissere dich, dass deine Serverumgebung sicher ist und das für deine App erwartete Datenverkehrsvolumen verarbeiten kann.

Abonniere nur die Webhookereignisse, die deine App benötigt. Damit kannst du die Latenz reduzieren, da deine App keine Payloads empfängt, die sie nicht benötigt.

Verwenden eines Webhookgeheimnisses

Du solltest ein Webhookgeheimnis für deine GitHub App festlegen und überprüfen, ob die Signatur der eingehenden Webhookereignisse mit dem Geheimnis übereinstimmt. Damit kannst du sicherstellen, dass ein eingehendes Webhookereignis ein gültiges GitHub-Ereignis ist.

Weitere Informationen findest du unter Verwenden von Webhooks mit GitHub-Apps. Ein Beispiel findest du unter Erstellen einer GitHub-App, die auf Webhookereignisse reagiert.

Benutzer*innen Zeit zum Akzeptieren neuer Berechtigungen einräumen

Wenn du deiner GitHub App Repository- oder Organisationsberechtigungen hinzufügst, erhalten Benutzer*innen, die die App in ihrem persönlichen Konto oder in ihrer Organisation installiert haben, eine E-Mail mit der Aufforderung, die neuen Berechtigungen zu überprüfen. Solange ein Benutzer oder eine Benutzerin die neuen Berechtigungen noch nicht genehmigt hat, erhält die App-Installation nur die alten Berechtigungen.

Wenn du Berechtigungen aktualisierst, solltest du erwägen, deine App abwärtskompatibel zu machen, damit deine Benutzerinnen genügend Zeit haben, die neuen Berechtigungen zu akzeptieren. Du kannst den Installationswebhook mit der Aktionseigenschaft new_permissions_accepted verwenden, um informiert zu werden, wenn Benutzerinnen neue Berechtigungen für deine App akzeptieren.

Sichere Nutzung von Diensten

Wenn deine App Dienste von Drittanbietern verwendet, müssen sie auf sichere Art und Weise genutzt werden:

Alle von deiner App genutzten Dienste sollten über einen eindeutigen Anmeldenamen und ein eindeutiges Kennwort verfügen.
Apps sollten keine Dienstkonten wie E-Mail- oder Datenbankdienste freigeben, um deinen SaaS-Dienst zu verwalten.
Nur Mitarbeiter*innen mit Verwaltungsaufgaben sollten Administratorzugriff auf die Infrastruktur haben, in der deine App gehostet wird.

Hinzufügen von Protokollierung und Überwachung

Füge ggf. Protokollierungs- und Überwachungsfunktionen für dein App hinzu. Ein Sicherheitsprotokoll kann Folgendes enthalten:

Authentisierungs- und Autorisierungsereignisse
Änderungen der Dienstkonfiguration
Lesen und Schreiben von Objekten
Benutzer- und Gruppenberechtigungsänderungen
Erhöhung der Rolle zum Administrator

Deine Protokolle sollten für jedes Ereignis konsistente Zeitstempelung verwenden und die Benutzer*innen, IP-Adressen oder Hostnamen für alle protokollierten Ereignisse aufzeichnen.

Aktivieren der Datenlöschung

Wenn deine GitHub App für andere Benutzerinnen oder Organisationen verfügbar sind, solltest du Benutzerinnen und Organisationsbesitzerinnen die Möglichkeit geben, ihre Daten zu löschen. Benutzerinnen sollten nicht per E-Mail oder telefonisch einen Suppormitarbeiterin kontaktieren müssen, um ihre Daten zu löschen.

In diesem Artikel