Skip to main content

Bereiche für OAuth-Apps

Anhand von Bereichen kannst du genau angeben, welche Art von Zugriff du benötigst. Bereiche beschränken den Zugriff für OAuth-Token. Sie gewähren keine zusätzlichen Berechtigungen über diejenigen hinaus, die der Benutzer bereits besitzt.

Hinweis: Erwäge, eine GitHub App anstelle einer OAuth app zu erstellen. GitHub Apps verwenden differenzierte Berechtigungen anstelle von Bereichen, die dir mehr Kontrolle über den Funktionsumfang deiner App geben. Weitere Informationen findest du unter Unterschiede zwischen GitHub-Apps und OAuth-Apps und unter Informationen zum Erstellen von GitHub-Apps.

Beim Einrichten einer OAuth app-App auf GitHub werden den Benutzer*innen angeforderte Bereiche im Autorisierungsformular angezeigt.

Hinweis: Wenn du eine GitHub-App erstellst, musst du keine Bereiche in deiner Autorisierungsanforderung bereitstellen. Weitere Informationen hierzu findest du unter Authentifizieren mit einer GitHub-App im Namen von Benutzer*innen.

Wenn deine OAuth app keinen Zugriff auf einen Browser hat, z. B. ein CLI-Tool, musst du keinen Bereich für Benutzer angeben, damit diese sich bei der App authentifizieren können. Weitere Informationen findest du unter Autorisieren von OAuth-Apps.

Überprüfe Kopfzeilen, um festzustellen, über welche OAuth-Bereiche du verfügst und was von der API-Aktion akzeptiert wird:

$ curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.github.com/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
  • X-OAuth-Scopes listet die Bereiche auf, die dein Token autorisiert hat.
  • X-Accepted-OAuth-Scopes enthält die Bereiche, auf die durch die Aktion geprüft wird.

Verfügbare Bereiche

NameBeschreibung
(no scope)Gewährt schreibgeschützten Zugriff auf öffentliche Informationen (einschließlich Benutzerprofilinformationen, Repositoryinformationen und Gists)
repoGewährt vollen Zugriff auf öffentliche und private Repositories, einschließlich Lese- und Schreibzugriff auf Code, Commit-Status, Repository-Einladungen, Mitarbeiter, Bereitstellungsstatus und Repository-Webhooks. Hinweis: Zusätzlich zu repositorybezogenen Ressourcen gewährt der repo-Bereich auch Zugriff auf die Verwaltung von organisationseigenen Ressourcen, einschließlich Projekten, Einladungen, Teammitgliedschaften und Webhooks. Dieser Bereich gewährt auch die Möglichkeit, Projekte im Besitz von Benutzer*innen zu verwalten.
repo:statusGewährt Lese-/Schreibzugriff auf Commitstatus in öffentlichen und privaten Repositorys. Dieser Bereich ist nur dafür erforderlich, anderen Benutzern oder Diensten Zugriff auf Commitstatus privater Repositorys zu gewähren, ohne Zugriff auf den Code zu gewähren.
repo_deploymentGewährt Zugriff auf Bereitstellungsstatus für öffentliche und private Repositorys. Dieser Bereich ist nur dafür erforderlich, um anderen Benutzern oder Diensten Zugriff auf den Einsatzstatus zu gewähren, ohne Zugriff auf den Code zu gewähren.
public_repoSchränkt den Zugang zu öffentlichen Repositories ein. Das umfasst Lese-/Schreibzugriff auf Code, Commitstatus, Repositoryprojekte, Projektmitarbeiter und Bereitstellungsstatus für öffentliche Repositorys und Organisationen. Auch für das Starten von öffentlichen Repositorys erforderlich.
repo:inviteGewährt Genehmigungs-/Ablehnungsfähigkeiten für Einladungen zur Zusammenarbeit an einem Repository. Dieser Bereich ist nur dafür erforderlich, anderen Benutzer*innen oder Diensten Zugriff auf Einladungen zu gewähren, ohne Zugriff auf den Code zu gewähren.
security_eventsGewährt:
Lese- und Schreibzugriff auf sicherheitsrelevante Ereignisse in der code scanning-API
Dieser Bereich ist nur notwendig, um anderen Benutzer*innen oder Diensten Zugang zu Sicherheitsereignissen zu gewähren, ohne dass sie Zugang zum Code erhalten.
admin:repo_hookGewährt Lese-, Schreib-, Ping- und Löschzugriff auf Repository-Hooks in öffentlichen oder privaten Repositorys. Die Bereiche repo und public_repo gewähren Vollzugriff auf Repositorys, einschließlich Repository-Hooks. Verwende den Bereich admin:repo_hook, um den Zugriff ausschließlich auf Repositoryhooks zu beschränken.
write:repo_hookGewährt Lese-, Schreib- und Pingzugriff auf Hooks in öffentlichen oder privaten Repositorys.
read:repo_hookGewährt Lese- und Pingzugriff auf Hooks in öffentlichen oder privaten Repositorys.
admin:orgVerwalten Sie die Organisation und ihre Teams, Projekte und Mitgliedschaften vollständig.
write:orgLese- und Schreibzugriff auf Organisationsmitgliedschaft und Organisationsprojekte.
read:orgSchreibgeschützter Zugriff auf Organisationsmitgliedschaft, Organisationsprojekte und Teammitgliedschaft.
admin:public_keyVerwalten Sie öffentliche Schlüssel vollständig.
write:public_keyErstellen Sie Details für öffentliche Schlüssel, listen Sie sie auf, und zeigen Sie sie an.
read:public_keyListen Sie Details für öffentliche Schlüssel auf, und zeigen Sie sie an.
admin:org_hookGewährt Lese-, Schreib-, Ping- und Löschzugriff auf Organisationshooks. Hinweis: OAuth-Token können diese Aktionen nur mit Organisationshooks ausführen, die von der OAuth app-App erstellt wurden. Über ein Personal access token kann diese Aktionen nur für Organisationshooks ausgeführt werden, die von einem Benutzer erstellt wurden.
gistGewährt Schreibzugriff auf Gists.
notificationsGewährt:
Lesezugriff auf die Benachrichtigungen von Benutzer*innen
Markieren als Lesezugriff auf Threads
Überwachen des Zugriffs auf ein Repository, Beenden des Überwachens des Zugriffs auf ein Repository und
Lese-, Schreib- und Löschzugriff auf Threadabonnements.
userGewährt nur Lese-/Schreibzugriff auf Profilinformationen. Beachte, dass dieser Bereich user:email und user:follow umfasst.
read:userGewährt Lesezugriff auf die Profildaten eines Benutzers.
user:emailGewährt Lesezugriff auf die E-Mail-Adressen eines Benutzers.
user:followGewährt Zugriff, um anderen Benutzern zu folgen oder nicht zu folgen.
projectGewährt Lese-/Schreibzugriff auf Benutzer und Organisation projects.
read:projectGewährt dem Benutzer und der Organisation nur Lesezugriff projects.
delete_repoGewährt Zugriff auf löschbare Repositorys.
write:packagesGewährt Zugriff zum Hochladen oder Veröffentlichen eines Pakets in GitHub Packages. Weitere Informationen findest du unter Veröffentlichen eines Pakets.
read:packagesGewährt Zugriff zum Herunterladen und Installieren von Paketen aus GitHub Packages. Weitere Informationen findest du unter Installieren eines Pakets.
delete:packagesGewährt Zugriff zum Löschen von Paketen aus GitHub Packages. Weitere Informationen findest du unter Löschen und Wiederherstellen eines Pakets.
admin:gpg_keyVollständige Verwaltung von GPG-Schlüsseln.
write:gpg_keyErstellen Sie Details für GPG-Schlüssel, listen Sie sie auf, und zeigen Sie sie an.
read:gpg_keyZeigen Sie Details zu GPG-Schlüsseln an.
codespaceGewährt die Möglichkeit, Codespaces zu erstellen und zu verwalten. Codespaces können ein GITHUB_TOKEN verfügbar machen, das möglicherweise andere Bereiche aufweist. Weitere Informationen finden Sie unter Sicherheit in GitHub Codespaces.
workflowErmöglicht das Hinzufügen und Aktualisieren von GitHub Actions-Workflowdateien. Workflowdateien können ohne diesen Bereich committet werden, wenn dieselbe Datei (mit demselben Pfad und demselben Inhalt) in einem anderen Branch im selben Repository vorhanden ist. Workflowdateien können ein GITHUB_TOKEN verfügbar machen, das möglicherweise andere Bereiche aufweist. Weitere Informationen finden Sie unter Automatische Tokenauthentifizierung.

Hinweis: Von deiner OAuth app können die Bereiche in der anfänglichen Umleitung angefordert werden. Du kannst mehrere Bereiche angeben, indem du diese mit einem Leerzeichen mit %20 voneinander trennst:

https://github.com/login/oauth/authorize?
  client_id=...&
  scope=user%20repo_deployment

Angeforderte Bereiche und gewährte Bereiche

Das Attribut scope enthält Bereiche, die dem Token zugeordnet sind und vom Benutzer gewährt wurden. Normalerweise sind diese Bereiche identisch mit den angeforderten. Benutzer können jedoch ihre Bereiche bearbeiten und deiner Anwendung effektiv weniger Zugriff gewähren, als du ursprünglich angefordert hast. Außerdem können Benutzer Tokenbereiche bearbeiten, nachdem der OAuth-Flow abgeschlossen wurde. Du solltest dir dieser Möglichkeit bewusst sein und das Verhalten deiner Anwendung entsprechend anpassen.

Es ist wichtig, Fehlerfälle zu behandeln, in denen dir ein Benutzer weniger Zugriff gewährt, als du ursprünglich angefordert hast. Von Anwendungen können die Benutzern z. B. gewarnt oder anderweitig informiert werden, dass der Funktionsumfang eingeschränkt wird oder dass sie einige Aktionen nicht ausführen können.

Die Benutzer können von den Anwendungen auch immer wieder durch den Flow zurückgeleitet werden, damit sie zusätzliche Berechtigungen erhalten. Denke aber immer daran, dass die Benutzer immer auch ablehnen können.

Unter Grundlagen des Authentifizierungshandbuchs findest du Tipps zur Behandlung von modifizierbaren Tokenbereichen.

Normalisierte Bereiche

Beim Anfordern mehrerer Bereiche wird das Token mit einer normalisierten Liste von Bereichen gespeichert. Dabei werden die Bereiche verworfen, die implizit in einem anderen angeforderten Bereich enthalten sind. Die Anforderung von user,gist,user:email führt z. B. zu einem Token mit den Bereichen user und gist, da der Zugriff, der mit dem Bereich user:email gewährt wird, im Bereich user enthalten ist.