Bereiche für OAuth-Apps

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

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

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.