Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
 

 

Identifying and authorizing users for GitHub Apps (Identifizieren und Autorisieren von Benutzer*innen für GitHub-Apps)

In this article

Ihre GitHub App kann Aktionen im Namen eines Benutzers ausführen, z. B. das Erstellen eines Issues, das Erstellen einer Bereitstellung und die Verwendung anderer unterstützter Endpunkte.

Hinweis: Auslaufende Benutzertoken sind derzeit ein optionales Feature und unterliegen Änderungen. Informationen zum Aktivieren oder Deaktivieren des Ablaufs von Benutzer-zu-Server-Token findest du unter Aktivieren optionaler Features für Apps. Weitere Informationen findest du unter Ablauf von Benutzer-zu-Server-Zugriffstoken für GitHub Apps.

Wenn die GitHub-App im Auftrag eines Benutzers eingesetzt wird, werden von ihr Benutzer-zu-Server-Anforderungen ausgeführt. Diese Anforderungen müssen mit dem Zugriffstoken eines Benutzers autorisiert werden. Benutzer-zu-Server-Anforderungen umfassen das Anfordern von Daten für einen Benutzer, z. B. die Bestimmung, welche Repositorys für einen bestimmten Benutzer angezeigt werden sollen. Diese Anforderungen enthalten auch Aktionen, die von einem Benutzer ausgelöst werden, z. B. das Ausführen eines Builds.

Um Token für den Zugriff von Benutzern auf Server sicherer zu gestalten, kannst du Zugriffstoken, die nach acht Stunden ablaufen, und ein Aktualisierungstoken verwenden, das gegen ein neues Zugriffstoken ausgetauscht werden kann. Weitere Informationen findest du unter Aktualisieren von Benutzer-zu-Server-Zugriffstoken.

Identifizieren von Benutzern auf der Website

Verwende den Webanwendungsfluss zum Autorisieren von Benutzer*innen für Standard-Apps, die im Browser ausgeführt werden.

Verwende den Gerätefluss zum Autorisieren von Benutzer*innen für monitorlose Apps ohne direkten Zugriff auf den Browser, z. B. CLI-Tools oder Git Credential Manager. Im Gerätefluss wird die Erweiterung OAuth 2.0 Device Authorization Grant verwendet.

Webanwendungsfluss

Mithilfe des Webanwendungsflusses läuft der Prozess zum Identifizieren von Benutzer*innen auf deiner Website wie folgt ab:

  1. Benutzer werden umgeleitet, um ihre GitHub-Identität anzufordern.
  2. Benutzer*innen werden von GitHub wieder zu deiner Website umgeleitet.
  3. Die GitHub-App greift mit dem Zugriffstoken des Benutzers auf die API zu.

Wenn du beim Erstellen oder Ändern der App Anfordern der Benutzerautorisierung (OAuth) während der Installation auswählst, wird Schritt 1 während der App-Installation abgeschlossen. Weitere Informationen findest du unter Autorisieren von Benutzer*innen während der Installation.

1. Anfordern der GitHub-Identität eines Benutzers

Leite den Benutzer bzw. die Benutzerin im Browser an die folgende URL weiter:

GET http(s)://HOSTNAME/login/oauth/authorize

Wenn von der GitHub-App ein login-Parameter angegeben wird, erfolgt die Benutzeraufforderung mit einem bestimmten Konto, das die Benutzer für die Anmeldung und Autorisierung der App verwenden können.

Parameter

NametypeBESCHREIBUNG
client_idstringErforderlich. Die Client-ID für die GitHub-App. Du kannst diese in den GitHub-App-Einstellungen finden, wenn du deine App auswählst. Hinweis: Die App-ID und die Client-ID sind nicht identisch und können nicht ausgetauscht werden.
redirect_uristringDie URL in der Anwendung, an die Benutzer nach der Autorisierung gesendet werden. Diese muss genau mit einer der URLs übereinstimmen, die du als Rückruf-URL bereitgestellt hast , als du deine GitHub-App eingerichtet hast, und darf keine zusätzlichen Parameter enthalten.
statestringDies sollte zum Schutz vor Fälschungsangriffen eine zufällige Zeichenfolge enthalten und könnte andere beliebige Daten umfassen.
loginstringSchlägt ein bestimmtes Konto vor, das zum Anmelden und Autorisieren der App verwendet werden soll.
allow_signupstringOb nicht authentifizierten Benutzern während des OAuth-Flusses eine Option zum Registrieren für GitHub angeboten wird. Der Standardwert ist true. Verwende false, wenn eine Richtlinie die Anmeldung verbietet.

Hinweis: Du musst keine Bereiche in der Autorisierungsanforderung angeben. Im Gegensatz zum herkömmlichen OAuth-Protokoll ist das Autorisierungstoken auf die Berechtigungen beschränkt, die der GitHub-App und denen des Benutzers zugeordnet sind.

2. Benutzer*innen werden von GitHub wieder zu deiner Website umgeleitet.

Wenn Benutzer*innen die Anforderung akzeptieren, werden sie von GitHub mit einem temporären code in einem Codeparameter sowie dem Status, den du im vorherigen Schritt in einem state-Parameter bereitgestellt hast, wieder zu deiner Website umgeleitet. Wenn die Status nicht übereinstimmen, wurde die Anforderung von Dritten erstellt und der Prozess sollte abgebrochen werden.

Hinweis: Wenn du beim Erstellen oder Ändern der App Anfordern der Benutzerautorisierung (OAuth) während der Installation auswählst, wird von GitHub ein temporärer code zurückgegeben, den du gegen ein Zugriffstoken austauschen musst. Der state-Parameter wird nicht zurückgegeben, wenn der OAuth-Fluss während der App-Installation von GibHub initiiert wird.

Tausche diesen code gegen ein Zugriffstoken aus. Wenn ablaufende Token aktiviert sind, läuft das Zugriffstoken in 8 Stunden ab, und das Aktualisierungstoken läuft in 6 Monaten ab. Jedes Mal, wenn du das Token aktualisierst, erhältst du ein neues Aktualisierungstoken. Weitere Informationen findest du unter Aktualisieren von Benutzer-zu-Server-Zugriffstoken.

Ablaufende Benutzertoken sind derzeit ein optionales Feature, bei dem sich Änderungen ergeben können. Wenn du das Feature für ablaufende Benutzer-zu-Server-Token aktivieren möchtest, findest du entsprechende Informationen unter Aktivieren optionaler Features für Apps.

Stelle eine Anforderung an den folgenden Endpunkt, um ein Zugriffstoken zu erhalten:

POST http(s)://HOSTNAME/login/oauth/access_token

Parameter

NametypeBESCHREIBUNG
client_idstringErforderlich. Die Client-ID für die GitHub-App.
client_secretstringErforderlich. Der geheime Clientschlüssel für die GitHub-App.
codestringErforderlich. Der Code, den du als Antwort auf Schritt 1 erhalten hast.
redirect_uristringDie URL in der Anwendung, an die Benutzer nach der Autorisierung gesendet werden. Diese muss genau mit einer der URLs übereinstimmen, die du als Rückruf-URL bereitgestellt hast , als du deine GitHub-App eingerichtet hast, und darf keine zusätzlichen Parameter enthalten.

Antwort

Standardmäßig weist die Antwort das folgende Format auf. Die Antwortparameter expires_in, refresh_token und refresh_token_expires_in werden nur zurückgegeben, wenn du ablaufende Benutzer-zu-Server-Zugriffstoken aktivierst.

{
  "access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "expires_in": 28800,
  "refresh_token": "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
  "refresh_token_expires_in": 15811200,
  "scope": "",
  "token_type": "bearer"
}

3. Die GitHub-App greift mit dem Zugriffstoken des Benutzers auf die API zu.

Das Zugriffstoken des Benutzers ermöglicht es der GitHub-App, Anforderungen im Auftrag eines Benutzers an die API zu senden.

Authorization: Bearer OAUTH-TOKEN
GET http(s)://HOSTNAME/api/v3/user

In curl kannst du beispielsweise den Autorisierungsheader wie folgt festlegen:

curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/user

Gerätefluss

Hinweis: Der Gerätefluss befindet sich in der öffentlichen Betaversion und kann geändert werden.

Mit dem Gerätefluss kannst du Benutzer*innen für eine monitorlose App autorisieren, z. B. ein CLI-Tool oder Git Credential Manager.

Weitere Informationen zum Autorisieren von Benutzer*innen mit dem Gerätefluss findest du unter Autorisieren von OAuth-Apps.

Überprüfen, auf welche Ressourcen der Installation ein Benutzer zugreifen kann

Sobald du über ein OAuth-Token für einen Benutzer oder eine Benutzerin verfügst, kannst du überprüfen, auf welche Installationen er oder sie zugreifen kann.

Authorization: Bearer OAUTH-TOKEN
GET /user/installations

Du kannst auch überprüfen, welche Repositorys für Benutzer*innen zum Installieren zugänglich sind.

Authorization: Bearer OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

Weitere Details findest du unter Auflisten der für das Benutzerzugriffstoken zugänglichen App-Installationen und Auflisten der für das Benutzerzugriffstoken zugänglichen Repositorys.

Behandeln einer widerrufenen GitHub-App-Autorisierung

Wenn ein Benutzer die Autorisierung einer GitHub-App widerruft, erhält die App standardmäßig den github_app_authorization-Webhook. GitHub-Apps können sich nicht von diesem Ereignis abmelden. Jede Person kann ihre Autorisierung einer GitHub-App über ihre Seite mit GitHub-Kontoeinstellungen widerrufen. Durch Widerrufen der Autorisierung einer GitHub-App wird die GitHub-App nicht deinstalliert. Du solltest deine GitHub-App so programmieren, dass sie nach dem Empfang dieses Webhooks die API nicht mehr im Auftrag der Person aufruft, die das Token widerrufen hat. Wenn deine GitHub-App ein widerrufenes Zugriffstoken weiterhin verwendet, erhält sie den Fehler 401 Bad Credentials.

Berechtigungen auf Benutzerebene

Du kannst der GitHub-App Berechtigungen auf Benutzerebene für den Zugriff auf Benutzerressourcen hinzufügen, z. B. auf E-Mails, die von einzelnen Benutzer*innen als Teil des Benutzerberechtigungsflusses gewährt werden. Berechtigungen auf Benutzerebene unterscheiden sich von Berechtigungen auf Repository- und Organisationsebene, die zum Zeitpunkt der Installation für eine Organisation oder ein persönliches Konto gewährt werden.

Du kannst Berechtigungen auf Benutzerebene in den Einstellungen der GitHub-App auf der Seite Berechtigungen und Webhooks im Abschnitt Benutzerberechtigungen auswählen. Weitere Informationen zum Auswählen von Berechtigungen findest du unter Bearbeiten der Berechtigungen einer GitHub-App.

Wenn Benutzerinnen deine App mit ihrem Konto installieren, werden in der Installationsaufforderung die Berechtigungen auf Benutzerebene aufgelistet, die von der App angefordert werden. Außerdem wird erläutert, dass einzelne Benutzerinnen von der App nach diesen Berechtigungen gefragt werden können.

Da Berechtigungen auf Benutzerebene für einzelne Benutzerinnen gewährt werden, kannst du diese der vorhandenen App hinzufügen, ohne Benutzerinnen zum Upgrade aufzufordern. Du musst vorhandene Benutzer*innen jedoch den Benutzerberechtigungsfluss durchlaufen lassen, um die neue Berechtigung zu autorisieren und ein neues Benutzer-zu-Server-Token für diese Anforderungen abzurufen.

Benutzer-zu-Server-Anforderungen

Während der Großteil der API-Interaktion unter Verwendung der Server-zu-Server-Zugriffstoken für die Installation erfolgen sollte, lassen es bestimmte Endpunkte zu, dass du Aktionen über die API mithilfe eines Benutzerzugriffstokens ausführst. Von der App können die folgenden Anforderungen mithilfe der GraphQL- oder REST-Endpunkte durchgeführt werden.

Unterstützte Endpunkte

Überprüfungsausführungen

Prüfsuiten

Verhaltensregeln

Bereitstellungsstatus

Bereitstellungen

Ereignisse

Feeds

Git-Blobs

Git-Commits

Git-Verweise

Git-Tags

Git-Strukturen

Gitignore-Vorlagen

Installationen

Issues zugewiesene Personen

Issue-Kommentare

Issue-Ereignisse

Issue-Zeitachse

Probleme

Bezeichnungen

Lizenzen

Markdown

Meta

Meilensteine

Organisationshooks

Organisationsmitglieder

Projektmitarbeiter außerhalb der Organisation

Pre-Receive-Hooks für eine Organisation

Teamprojekte einer Organisation

Teamrepositorys einer Organisation

Organisationsteams

Organisationen

Projektmitarbeiter

Projekte

Pullkommentare

Überprüfungsereignisse für Pull Requests

Überprüfungsanforderungen für Pull Requests

Prüfer von Pull Requests

Pulls

Reaktionen

Repositorys

Repositoryaktivität

Repositorybranches

Projektmitarbeiter für Repositorys

Commitkommentare für Repositorys

Repositorycommits

Repositorycommunity

Repositoryinhalte

Repositoryereignisdispatches

Repositoryhooks

Repositoryeinladungen

Repositoryschlüssel

Repositoryseiten

Pre-Receive-Hooks für Repository

Repositoryreleases

Repositorystatistiken

Root

Suche

Status

Teamdiskussionen

Themen

Benutzer-E-Mails

Benutzerfollower

Benutzer-GPG-Schlüssel

Öffentliche Schlüssel für Benutzer

Benutzer

Weiterführende Themen