Migrieren von OAuth-Apps zu -Apps

In diesem Artikel

Es wird empfohlen, Apps für die Integration in zu verwenden. Apps bieten viele Vorteile gegenüber OAuth apps, einschließlich:

  • Verbesserte Sicherheitsfeatures (z. B. differenzierte Berechtigungen, Optionen für den Repositoryzugriff und kurzlebige Tokens)
  • Möglichkeit, unabhängig von oder im Namen von Benutzenden zu handeln
  • Skalierbare Ratenlimits
  • Integrierte Webhooks

Weitere Informationen finden Sie unter Informationen zum Erstellen von -Apps.

Die folgenden Schritte stellen einen Überblick über die Migration von einer OAuth app zu einer App dar. Die genauen Schritte hängen von deiner App ab.

Sieh dir den Code für deine OAuth app noch einmal genau an. Die API-Anforderungen, die deine OAuth app tätigt, helfen dir bei der Entscheidung, welche Berechtigungen für deine App ausgewählt werden sollten.

Darüber hinaus gibt es einige REST-API-Endpunkte, die für OAuth apps nicht verfügbar sind. Im Artikel Für -App-Installationszugriffstoken verfügbare Endpunkte findest du Informationen dazu, ob deine verwendeten REST-Endpunkte für Apps verfügbar sind.

Registriere eine neue App. Weitere Informationen finden Sie unter Registrieren einer -App.

Im Vergleich zu einer OAuth app hast du bei einer App mehr Kontrolle über die Einstellungen. Weitere wichtige Vorteile sind:

  • Im Gegensatz zu einer OAuth app, der immer im Namen eines Benutzers oder einer Benutzerin handelt, kann eine App eigenständig oder im Namen eines Benutzers oder einer Benutzerin handeln. Wenn deine neue App nicht im Namen eines Benutzers oder einer Benutzerin handeln soll, kannst du die Einstellungen „Benutzer*innen identifizieren und autorisieren“ überspringen. Weitere Informationen finden Sie unter Informationen zur Authentifizierung mit einer -App.

  • Du kannst Webhooks verwenden, um deine App zu benachrichtigen, wenn bestimmte Ereignisse auftreten. Im Gegensatz zu Webhooks für OAuth apps, die du über die API für jedes Repository oder jede Organisation konfigurieren musst, sind Webhooks in Apps integriert. Wenn du deine App registrierst, kannst du die Webhookereignisse auswählen, die du empfangen möchtest. Wenn deine OAuth app derzeit mithilfe von Abrufen ermittelt, ob ein Ereignis aufgetreten ist, solltest du stattdessen Webhooks abonnieren, damit deine App innerhalb des Ratenlimits bleibt. Weitere Informationen finden Sie unter Verwenden von Webhooks mit -Apps.

  • Bei einer OAuth app werden Bereiche angefordert, wenn eine Benutzerin deine App autorisiert. Bei einer App gibst du Berechtigungen in den App-Einstellungen an. Diese Berechtigungen sind präziser als Bereiche und ermöglichen es dir, nur die Berechtigungen auszuwählen, die deine App benötigt. Darüber hinaus werden diese Berechtigungen REST-API-Endpunkten und Webhookereignissen zugeordnet, sodass du leicht bestimmen kannst, welche Berechtigungen deine App benötigt, um auf einen bestimmten REST-API-Endpunkt zuzugreifen oder einen bestimmten Webhook zu abonnieren. Die Berechtigungen für GraphQL-Anforderungen sind derzeit nicht dokumentiert. Weitere Informationen finden Sie unter Auswählen von Berechtigungen für eine -App.

Nachdem du eine App registriert hast, musst du den Code der alten OAuth app anpassen, damit diese mit der neuen App kompatibel ist.

Du musst den Code deiner App aktualisieren, um die API-Authentifizierung für deine App zu verarbeiten. Eine App kann sich auf drei Arten authentifizieren:

Wenn du die offizielle Octokit.js-Bibliothek von nutzt, kannst du das integrierte App-Objekt zur Authentifizierung verwenden. Beispiele findest du unter Skripterstellung mit der REST-API und JavaScript und Erstellen einer -App, die auf Webhookereignisse reagiert.

Überprüfe die Unterschiede der Ratenlimits zwischen OAuth apps und Apps. Für Apps werden Gleitregeln für Ratenlimits verwendet, die basierend auf der Anzahl der Repositorys und Benutzer*innen in der Organisation erhöht werden können. Weitere Informationen finden Sie unter Rate limits for Apps (Ratenbegrenzungen für -Apps).

Ziehe nach Möglichkeit die Verwendung bedingter Anforderungen und das Abonnieren von Webhooks anstelle von Abfragen in Betracht, damit die Ratenlimits nicht überschritten werden. Weitere Informationen zu bedingten Anforderungen findest du unter Bewährte Methoden für die Verwendung der REST-API. Weitere Informationen zum Verwenden von Webhooks mit deiner App findest du unter Verwenden von Webhooks mit -Apps und Erstellen einer -App, die auf Webhookereignisse reagiert.

Teste deine neue App, um dich zu vergewissern, dass der Code wie erwartet funktioniert.

Wenn die Verwendung der neuen App durch andere Konten möglich sein soll, muss deine App öffentlich sein. Damit deine App leichter gefunden werden kann, kannst du sie im Marketplace listen. Weitere Informationen findest du unter Informationen zu Marketplace für Apps und Öffentlich- oder Privatmachen einer -App.

Sobald deine neue App bereit ist, weise die Benutzerinnen der alten OAuth app an, zur neuen App zu migrieren. Es gibt keine Möglichkeit, die Benutzerinnen automatisch zu migrieren. Jeder Benutzerin muss die App selbst installieren und/oder autorisieren.

Als App-Besitzerin solltest du Handlungsaufrufe einrichten, um die Benutzerinnen dazu zu ermutigen, die neue App zu installieren und zu autorisieren und die Autorisierung für die alte OAuth app zu widerrufen. Auch die Dokumentation und Benutzeroberflächenelemente sollten entsprechend aktualisiert werden.

Wenn deine App eigenständig API-Anforderungen tätigen oder auf Organisations- oder Repositoryressourcen zugreifen soll, muss der oder die Benutzerin deine App installieren. Wenn eine Benutzerin eine App für ein Konto oder eine Organisation installiert, wählt dieser aus, auf welche Repositorys die App zugreifen kann, und erteilt der App die angeforderten Organisations- und Repositoryberechtigungen.

Um Benutzer*innen bei der Installation deiner App zu unterstützen, kannst du einen Link zur Website der App hinzufügen, den diese auswählen können, um die App zu installieren. Die Installations-URL hat folgendes Format: https://.com/apps/YOUR_APP_NAME/installations/new. Ersetze YOUR_APP_NAME durch den Platzhalternamen deiner App. Diesen findest du im Feld „Öffentlicher Link“ auf der Einstellungsseite für deine App.

Um die Repositorys vorab auszuwählen, auf die deine OAuth app Zugriff hatte, kannst du /permissions und Abfrageparameter an die Installations-URL anfügen. Dadurch können die Benutzer*innen der App leichter Zugriff auf die Repositorys erteilen, auf die deine OAuth app bereits Zugriff hatte. Die Abfrageparameter lauten:

  • suggested_target_id: Die ID des Benutzers bzw. der Benutzerin oder der Organisation, die deine App installiert. Dieser Parameter ist erforderlich.
  • repository_ids[]: Die Repository-IDs, die für die Installation ausgewählt werden sollen. Wenn keine angegeben werden, werden alle Repositorys ausgewählt. Die maximale Anzahl von Repositorys, die vorab ausgewählt werden können, beträgt 100. Verwende die Endpunkte Repositorys für den authentifizierten Benutzer auflisten und Organisationsrepositorys auflisten, um eine Liste der Repositorys abzurufen, auf die deine OAuth app Zugriff hat.

Beispiel: https://.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID

Weitere Informationen zum Installieren von Apps findest du unter Installieren einer -App aus dem Marketplace für dein persönliches Konto, Installieren einer -App aus dem Marketplace für deine Organisationen, Installieren einer -App von einem Drittanbieter und Installieren einer eigenen -App.

Wenn deine App API-Anforderungen im Namen eines Benutzers oder einer Benutzerin tätigen sollen, muss der oder die Benutzerin die App autorisieren. Wenn Benutzerinnen eine App autorisieren, gewähren sie der App die Berechtigung, in ihrem Namen zu handeln, sowie die von der App angeforderten Kontoberechtigungen. Wenn die App in einem Organisationskonto installiert ist, muss jeder Benutzerin innerhalb dieser Organisation die App autorisieren, damit die App in dessen oder deren Namen handeln kann.

Führe die Benutzer*innen durch den Webanwendungs- oder Geräteablauf zur Autorisierung deiner App. Weitere Informationen finden Sie unter Generieren eines Benutzerzugriffstokens für eine -App.

Weitere Informationen zum Autorisieren von Apps findest du unter Autorisieren von -Apps.

Du solltest deinen Benutzerinnen empfehlen, die Zugriffsberechtigungen der alten OAuth app zu widerrufen. Dadurch wird ein vollständiger Umstieg von der OAuth app erreicht, und die Daten der Benutzerinnen bleiben geschützt. Weitere Informationen finden Sie unter Überprüfen der autorisierten OAuth-Apps.

Du solltest alle Benutzeroberflächen oder Dokumentationen im Zusammenhang mit deiner App aktualisieren, um die Änderung von OAuth app in App widerzuspiegeln.

Wenn eine Benutzerin deine App installiert und Zugriff auf ein Repository gewährt, solltest du alle Webhooks für die alte OAuth app entfernen. Andernfalls reagieren deine neue App und deine alte OAuth app auf Webhooks für dasselbe Ereignis.

Um Repositorywebhooks zu entfernen, kannst du dem installation_repositories-Webhook mit der added-Aktion lauschen. Wenn deine App dieses Ereignis empfängt, kannst du die REST-API verwenden, um den Webhook für diese Repositorys für deine OAuth app zu löschen. Weitere Informationen findest du unter Webhook-Ereignisse und -Nutzlasten und REST-API-Endpunkte für Repository-Webhooks.

Um Organisationswebhooks zu entfernen, kannst du dem installation-Webhook mit der created-Aktion lauschen. Wenn deine App dieses Ereignis für eine Organisation empfängt, kannst du die REST-API verwenden, um den Webhook für diese Organisation und die zugehörigen Repositorys für deine OAuth app zu löschen. Weitere Informationen findest du unter Webhook-Ereignisse und -Nutzlasten, REST-API-Endpunkte für Organisationswebhooks und REST-API-Endpunkte für Repository-Webhooks.

Nachdem deine Benutzer*innen zur neuen App migriert sind, solltest du die alte OAuth app löschen. Dadurch wird der Missbrauch der Anmeldeinformationen für die OAuth app vermieden. Außerdem werden alle verbleibenden Autorisierungen der OAuth app widerrufen. Weitere Informationen finden Sie unter Löschen einer OAuth-App. Wenn deine OAuth app auf Marketplace gelistet ist, musst du dich möglicherweise an den -Support wenden, um deine App zuerst aus dem Marketplace zu entfernen.