Note
Du solltest in Betracht ziehen, eine GitHub App anstelle einer OAuth app zu erstellen.
Sowohl GitHub Apps als auch OAuth apps verwenden OAuth 2.0.
GitHub Apps können ähnlich wie eine OAuth app im Auftrag von Benutzerinnen handeln, oder für sich selbst, was für Automatisierungen von Vorteil ist, die keine Benutzereingabe erfordern. Außerdem verwendet GitHub Apps differenzierte Berechtigungen, bietet Benutzerinnen mehr Kontrolle darüber, auf welche Repositorys die App zugreifen kann, und verwendet kurzlebige Token. Weitere Informationen findest du unter Unterschiede zwischen GitHub-Apps und OAuth-Apps und Informationen zum Erstellen von GitHub-Apps.
Die OAuth-Implementierung von GitHub unterstützt den Standardautorisierungscode-Gewährungstyp und die OAuth 2.0-Geräteautorisierungserteilung für Apps, die keinen Zugriff auf einen Webbrowser haben.
Wenn Sie die Autorisierung Ihrer App auf übliche Art überspringen möchten, z. B. beim Testen Ihrer App, können Sie den Nicht-Webanwendungsfluss verwenden.
Überlege für die Autorisierung deiner OAuth app, welcher Autorisierungsfluss am besten zu deiner App passt.
- Webanwendungsfluss: Wird verwendet, um Benutzer*innen für Standard-OAuth apps zu autorisieren, die im Browser ausgeführt werden. (Der implizite Gewährungstyp wird nicht unterstützt.)
- Gerätefluss: Wird für Headless-Apps verwendet, z. B. CLI-Tools.
Webanwendungsfluss
Note
Wenn du eine GitHub-App erstellst, kannst du den OAuth-Webanwendungsfluss weiterhin verwenden, aber das Setup hat einige wichtige Unterschiede. Weitere Informationen findest du unter Authentifizieren mit einer GitHub-App im Namen von Benutzer*innen.
Der Webanwendungsfluss zum Autorisieren von Benutzer*innen für deine App lautet wie folgt:
- Benutzer werden umgeleitet, um ihre GitHub-Identität anzufordern.
- Benutzer*innen werden von GitHub wieder zu deiner Website umgeleitet.
- Die App greift mit dem Zugriffstoken des Benutzers auf die API zu.
1. Anfordern der GitHub-Identität eines Benutzers
GET https://github.com/login/oauth/authorize
Dieser Endpunkt akzeptiert die folgenden Eingabeparameter.
Query parameter (Abfrageparameter) | type | Erforderlich? | Beschreibung |
---|---|---|---|
client_id | string | Erforderlich | Die Client-ID, die Sie von GitHub bei Ihrer Registrierung erhalten haben. |
redirect_uri | string | Dringend empfohlen | Die URL in der Anwendung, an die Benutzer nach der Autorisierung gesendet werden. Weitere Informationen zu Umleitungs-URLs finden Sie unten. |
login | string | Optional | Schlägt ein bestimmtes Konto vor, das zum Anmelden und Autorisieren der App verwendet werden soll. |
scope | string | Kontextabhängig | Eine durch Leerzeichen getrennte Liste von Bereichen. Falls nicht angegeben, wird für scope standardmäßig eine leere Liste für Benutzer verwendet, die keine Bereiche für die Anwendung autorisiert haben. Für Benutzer, die über autorisierte Bereiche für die Anwendung verfügen, wird nicht die OAuth-Autorisierungsseite mit der Liste der Bereiche angezeigt. Stattdessen wird dieser Schritt des Flusses automatisch mit den Bereichen abgeschlossen, die der Benutzer für die Anwendung autorisiert hat. Wenn ein Benutzer beispielsweise den Webfluss schon zweimal ausgeführt hat und ein Token mit dem Bereich user und ein anderes Token mit dem Bereich repo autorisiert hat, erhält ein dritter Webfluss, der keinen Bereich (scope ) bereitstellt, ein Token mit dem Bereich user und repo . |
state | string | Dringend empfohlen | Eine nicht erratbare zufällige Zeichenfolge. Sie wird verwendet, um vor websiteübergreifenden Anforderungsfälschungen zu schützen. |
allow_signup | string | Optional | Gibt an, ob nicht authentifizierten Benutzern während des OAuth-Flusses eine Option zum Registrieren für GitHub angeboten wird. Der Standardwert lautet true . Verwende false , wenn eine Richtlinie die Anmeldung verbietet. |
prompt | string | Optional | Erzwingt die Anzeige der Kontoauswahl, wenn auf select_account eingestellt. Die Kontoauswahl wird auch angezeigt, wenn die Anwendung über einen Nicht-HTTP-Umleitungs-URI verfügt oder wenn Sie bei mehreren Konten angemeldet sind. |
Die PKCE-Parameter (Proof Key for Code Exchange) code_challenge
und code_challenge_method
werden derzeit nicht unterstützt. CORS-Preflightanforderungen (OPTIONS) werden derzeit nicht unterstützt.
2. Benutzer*innen werden von GitHub wieder zu deiner Website umgeleitet.
Wenn der Benutzer die Anforderung akzeptiert, wird er von GitHub mit einem temporären code
in einem Codeparameter sowie dem Status, den Sie im vorherigen Schritt in einem state
-Parameter bereitgestellt haben, wieder zu Ihrer Website umgeleitet. Der temporäre Code läuft nach 10 Minuten ab. Wenn die Zustände nicht übereinstimmen, hat ein Dritter die Anforderung erstellt, und Sie sollten den Prozess abbrechen.
Tausche diesen code
gegen ein Zugriffstoken aus:
POST https://github.com/login/oauth/access_token
Dieser Endpunkt akzeptiert die folgenden Eingabeparameter.
Parametername | type | Erforderlich? | Beschreibung |
---|---|---|---|
client_id | string | Erforderlich | Die Client-ID, die Sie von GitHub für Ihre OAuth app erhalten haben. |
client_secret | string | Erforderlich | Der geheime Clientschlüssel, den Sie von GitHub für Ihre OAuth app erhalten haben. |
code | string | Erforderlich | Der Code, den Sie als Antwort auf Schritt 1 erhalten haben. |
redirect_uri | string | Dringend empfohlen | Die URL in der Anwendung, an die Benutzer nach der Autorisierung gesendet werden. Dies kann zur Abgleichung mit dem ursprünglich bei der Austellung von code bereitgestellten URI verwendet werden, um Angriffe auf Ihren Dienst zu verhindern. |
Standardmäßig weist die Antwort das folgende Format auf:
access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&scope=repo%2Cgist&token_type=bearer
Du kannst die Antwort auch in verschiedenen Formaten empfangen, wenn du das Format in der Accept
-Kopfzeile angibst. Beispielweise Accept: application/json
oder Accept: application/xml
:
Accept: application/json
{
"access_token":"gho_16C7e42F292c6912E7710c838347Ae178B4a",
"scope":"repo,gist",
"token_type":"bearer"
}
Accept: application/xml
<OAuth>
<token_type>bearer</token_type>
<scope>repo,gist</scope>
<access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
</OAuth>
3. Verwenden des Zugriffstokens für den Zugriff auf die API
Mit dem Zugriffstoken können Sie Anforderungen an die API im Namen eines Benutzers vornehmen.
Authorization: Bearer OAUTH-TOKEN
GET https://api.github.com/user
In curl können Sie beispielsweise den Autorisierungsheader wie folgt festlegen:
curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.github.com/user
Jedes Mal, wenn Sie ein Zugriffstoken empfangen, sollten Sie das Token zur erneuten Überprüfung der Benutzeridentität verwenden. Benutzer*innen können ändern, bei welchem Konto sie angemeldet sind, wenn Sie Ihnen die App-Authorisierung senden, und Sie riskieren das Mischen von Benutzerdaten, wenn Sie die Benutzeridentität nicht nach jeder Anmeldung überprüfen.
Gerätefluss
Mit dem Gerätefluss kannst du Benutzer*innen für eine monitorlose Anwendung autorisieren, z. B. ein CLI-Tool oder den Git Credential Manager.
Bevor Sie den Gerätefluss verwenden können, um Benutzer zu autorisieren und zu identifizieren, müssen Sie ihn zuerst in den Einstellungen Ihrer App aktivieren. Weitere Informationen zum Aktivieren des Geräteflusses in deiner App findest du unter Ändern einer GitHub-App-Registrierung für GitHub Apps und Ändern einer OAuth-App für OAuth apps.
Übersicht über den Gerätefluss
- Deine App fordert Geräte- und Benutzerüberprüfungscodes an und ruft die Autorisierungs-URL ab, in die die Benutzer*innen den Benutzerüberprüfungscode eingeben.
- Die App fordert den Benutzer auf, einen Benutzerüberprüfungscode bei
https://github.com/login/device
einzugeben. - Die App fragt den Benutzerauthentifizierungsstatus ab. Nachdem der Benutzer das Gerät autorisiert hat, kann die App API-Aufrufe mit einem neuen Zugriffstoken tätigen.
Schritt 1: App fordert die Geräte- und Benutzerüberprüfungscodes von GitHub an
POST https://github.com/login/device/code
Deine App muss einen Benutzerüberprüfungscode und eine Überprüfungs-URL anfordern, die die App verwendet, um die Benutzer*innen im nächsten Schritt zum Authentifizieren aufzufordern. Diese Anforderung gibt auch einen Geräteüberprüfungscode zurück, den die App verwenden muss, um ein Zugriffstoken zu empfangen und den Status der Benutzerauthentifizierung zu überprüfen.
Der Endpunkt akzeptiert die folgenden Eingabeparameter.
Parametername | Type | BESCHREIBUNG |
---|---|---|
client_id | string | Erforderlich. Die Client-ID, die Sie von GitHub für Ihre App erhalten haben. |
scope | string | Eine durch Leerzeichen getrennte Liste der Bereiche, auf die deine App Zugriff anfordert. Weitere Informationen finden Sie unter Bereiche für OAuth-Apps. |
Standardmäßig weist die Antwort das folgende Format auf:
device_code=3584d83530557fdd1f46af8289938c8ef79f9dc5&expires_in=900&interval=5&user_code=WDJB-MJHT&verification_uri=https%3A%2F%2Fgithub.com%2Flogin%2Fdevice
Parametername | Type | BESCHREIBUNG |
---|---|---|
device_code | string | Der Geräteüberprüfungscode umfasst 40 Zeichen und wird verwendet, um das Gerät zu überprüfen. |
user_code | string | Der Benutzerüberprüfungscode wird auf dem Gerät angezeigt, damit der Benutzer den Code in einen Browser eingeben kann. Dieser Code umfasst 8 Zeichen mit einem Bindestrich in der Mitte. |
verification_uri | string | Die Überprüfungs-URL, in der Benutzer den Benutzercode (user_code ) eingeben müssen: https://github.com/login/device . |
expires_in | integer | Die Anzahl der Sekunden, bevor device_code und user_code ablaufen. Der Standardwert beträgt 900 Sekunden (oder 15 Minuten). |
interval | integer | Die Zeit in Sekunden, die mindestens verstreichen muss, bevor Sie eine neue Zugriffstokenanforderung (POST https://github.com/login/oauth/access_token ) vornehmen können, um die Geräteautorisierung abzuschließen. Wenn das Intervall beispielsweise 5 ist, können Sie erst eine neue Anforderung vornehmen, wenn 5 Sekunden vergangen sind. Wenn Sie mehr als eine Anforderung in 5 Sekunden vornehmen, wird der Grenzwert für die Rate erreicht und ein slow_down -Fehler angezeigt. |
Du kannst die Antwort auch in verschiedenen Formaten empfangen, wenn du das Format in der Accept
-Kopfzeile angibst. Beispielweise Accept: application/json
oder Accept: application/xml
:
Accept: application/json
{
"device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
"user_code": "WDJB-MJHT",
"verification_uri": "https://github.com/login/device",
"expires_in": 900,
"interval": 5
}
Accept: application/xml
<OAuth>
<device_code>3584d83530557fdd1f46af8289938c8ef79f9dc5</device_code>
<user_code>WDJB-MJHT</user_code>
<verification_uri>https://github.com/login/device</verification_uri>
<expires_in>900</expires_in>
<interval>5</interval>
</OAuth>
Schritt 2: Fordere den Benutzer auf, den Benutzercode in einen Browser einzugeben
Dein Gerät zeigt den Benutzerüberprüfungscode an und fordert die Benutzer*innen auf, den Code unter https://github.com/login/device
einzugeben.
Schritt 3: App fragt GitHub ab, um zu überprüfen, ob der Benutzer das Gerät autorisiert hat
POST https://github.com/login/oauth/access_token
Deine App stellt Geräteautorisierungsanforderungen, die POST https://github.com/login/oauth/access_token
abfragen, bis Geräte- und Benutzercodes ablaufen oder Benutzer*innen die App erfolgreich mit einem gültigen Benutzercode autorisiert haben. Die App muss das Mindestabrufintervall (interval
) verwenden, das in Schritt 1 abgerufen wird, um Fehler durch Ratenbegrenzung zu vermeiden. Weitere Informationen findest du unter Ratenbegrenzungen für den Gerätefluss.
Der Benutzer muss innerhalb von 15 Minuten (oder 900 Sekunden) einen gültigen Code eingeben. Nach 15 Minuten müssen Sie mit POST https://github.com/login/device/code
einen neuen Geräteautorisierungscode anfordern.
Nachdem der Benutzer autorisiert wurde, erhält die App ein Zugriffstoken, das verwendet werden kann, um im Auftrag eines Benutzers Anforderungen an die API vorzunehmen.
Der Endpunkt akzeptiert die folgenden Eingabeparameter.
Parametername | Type | BESCHREIBUNG |
---|---|---|
client_id | string | Erforderlich. Die Client-ID, die Sie von GitHub für Ihre OAuth app erhalten haben. |
device_code | string | Erforderlich. Die von der POST https://github.com/login/device/code -Anforderungen empfangene device_code . |
grant_type | string | Erforderlich. Der Gewährungstyp muss urn:ietf:params:oauth:grant-type:device_code sein. |
Standardmäßig weist die Antwort das folgende Format auf:
access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&token_type=bearer&scope=repo%2Cgist
Du kannst die Antwort auch in verschiedenen Formaten empfangen, wenn du das Format in der Accept
-Kopfzeile angibst. Beispielweise Accept: application/json
oder Accept: application/xml
:
Accept: application/json
{
"access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
"token_type": "bearer",
"scope": "repo,gist"
}
Accept: application/xml
<OAuth>
<access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
<token_type>bearer</token_type>
<scope>gist,repo</scope>
</OAuth>
Grenzwerte für den Gerätefluss
Wenn ein Benutzer den Überprüfungscode im Browser sendet, gibt es einen Grenzwert von 50 Übermittlungen in einer Stunde pro Anwendung.
Wenn Sie mehr als eine Zugriffstokenanforderung (POST https://github.com/login/oauth/access_token
) innerhalb des erforderlichen Mindestzeitrahmens zwischen Anforderungen (oder interval
) vornehmen, wird der Grenzwert für die Rate erreicht und ein slow_down
-Fehler angezeigt. Die slow_down
-Fehlerantwort fügt dem letzten Intervall (interval
) 5 Sekunden hinzu. Weitere Informationen finden Sie unter Fehlercodes für den Gerätefluss.
Fehlercodes für den Gerätefluss
Fehlercode | BESCHREIBUNG |
---|---|
authorization_pending | Dieser Fehler tritt auf, wenn die Autorisierungsanforderung aussteht und der Benutzer noch nicht den Benutzercode eingegeben hat. Von der App wird erwartet, dass sie weiterhin die POST https://github.com/login/oauth/access_token -Anforderung ohne Überschreiten des Intervalls (interval ) abfragt, was eine Mindestanzahl von Sekunden zwischen jeder Anforderung erfordert. |
slow_down | Wenn Sie den Fehler slow_down erhalten, werden 5 zusätzliche Sekunden dem Mindestintervall (interval ) oder -zeitrahmen hinzugefügt, das bzw. der zwischen Ihren Anforderungen mit POST https://github.com/login/oauth/access_token erforderlich ist. Wenn beispielsweise für das Startintervall mindestens 5 Sekunden zwischen Anforderungen erforderlich waren und ein slow_down -Fehler angezeigt wird, müssen Sie jetzt mindestens 10 Sekunden warten, bevor Sie eine neue Anforderung für ein OAuth-Zugriffstoken vornehmen. Die Fehlerantwort enthält den neuen Wert für interval , den Sie verwenden müssen. |
expired_token | Wenn der Gerätecode abgelaufen ist, wird der token_expired -Fehler angezeigt. Du musst eine neue Anforderung für einen Gerätecode vornehmen. |
unsupported_grant_type | Der Gewährungstyp muss urn:ietf:params:oauth:grant-type:device_code sein und als Eingabeparameter enthalten sein, wenn Sie die OAuth-Tokenanforderung POST https://github.com/login/oauth/access_token abfragen. |
incorrect_client_credentials | Für den Gerätefluss müssen Sie die Client-ID Ihrer App übergeben, die Sie auf der Seite „Einstellungen“ Ihrer App finden. Der geheime Clientschlüssel (client_secret ) ist für den Gerätefluss nicht erforderlich. |
incorrect_device_code | Der angegebene device_code ist ungültig. |
access_denied | Wenn Benutzerinnen während des Autorisierungsprozesses auf „Abbrechen“ klickt, wird ein access_denied -Fehler angezeigt, und die Bentutzerinnen können den Überprüfungscode nicht noch einmal verwenden. |
device_flow_disabled | Der Gerätefluss wurde in den Einstellungen der App nicht aktiviert. Weitere Informationen findest du unter Gerätefluss. |
Weitere Informationen findest du unter OAuth 2.0-Geräteautorisierungszuweisung.
Nicht-Webanwendungsfluss
Nicht-Webauthentifizierung ist für begrenzte Situationen wie Tests verfügbar. Bei Bedarf können Sie mithilfe der Standardauthentifizierung ein personal access token mithilfe Ihrer personal access token-Einstellungsseite erstellen. Mit dieser Technik kann der Benutzer den Zugriff jederzeit widerrufen.
Umleitungs-URLs
Das redirect_uri
ist optional. Wird die Angabe weggelassen, leitet GitHub Benutzer*innen an die Rückruf-URL um, die in den OAuth app-Einstellungen konfiguriert ist. Wenn angegeben, müssen Host (Unterdomänen ausgenommen) und Port der Umleitungs-URL genau mit der Rückruf-URL übereinstimmen. Der Pfad der Umleitungs-URL muss auf ein Unterverzeichnis der Rückruf-URL verweisen.
CALLBACK: http://example.com/path
GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
GOOD: http://oauth.example.com/path
GOOD: http://oauth.example.com/path/subdir/other
BAD: http://example.com/bar
BAD: http://example.com/
BAD: http://example.com:8080/path
BAD: http://oauth.example.com:8080/path
BAD: http://example.org
Loopback-Umleitungs-URLs
Der optionale Parameter redirect_uri
kann auch für Loopback-URLs verwendet werden, was für native Anwendungen auf einem Desktopcomputer sinnvoll ist. Wenn die Anwendung eine Loopback-URL und einen Port angibt, werden Benutzer nach der Autorisierung der Anwendung an die angegebene URL und den Port weitergeleitet. Der redirect_uri
muss nicht mit dem Port übereinstimmen, der in der Rückruf-URL für die App angegeben ist.
Für die Rückruf-URL http://127.0.0.1/path
kann redirect_uri
verwendet werden, wenn die Anwendung auf Port 1234
lauscht:
http://127.0.0.1:1234/path
Beachte, dass OAuth RFC empfiehlt, nicht localhost
zu verwenden, sondern stattdessen Loopback-Literal 127.0.0.1
oder IPv6 ::1
.
Erstellen mehrerer Token für OAuth apps
Du kannst mehrere Token für eine Kombination aus Benutzer/Anwendung/Bereich erstellen, um Token für bestimmte Anwendungsfälle zu erstellen.
Dies ist nützlich, wenn deine OAuth app einen Workflow unterstützt, der GitHub für die Anmeldung verwendet und nur grundlegende Benutzerinformationen erfordert. Ein anderer Workflow kann den Zugriff auf private Repositorys eines Benutzers erfordern. Mithilfe mehrerer Token kann deine OAuth app den Webfluss für jeden Anwendungsfall ausführen und nur die erforderlichen Bereiche anfordern. Wenn Benutzer*innen deine Anwendung nur zum Anmelden verwenden, müssen sie deiner OAuth app nie Zugriff auf ihre privaten Repositorys gewähren.
Es gibt eine Obergrenze von zehn Token, die pro Nutzer/Anwendung/Geltungsbereich-Kombination ausgegeben werden, und eine Ratebegrenzung von zehn Token, die pro Stunde erstellt werden. Wenn eine Anwendung mehr als zehn Token für denselben Benutzer und dieselben Bereiche erstellt, werden die ältesten Token mit derselben Kombination aus Benutzer, Anwendung und Bereich entzogen. Das Erreichen der Stundensatzgrenze führt jedoch nicht zum Entzug des ältesten Tokens. Stattdessen wird eine Aufforderung zur erneuten Autorisierung im Browser ausgelöst, und der Benutzer wird aufgefordert, die der App gewährten Berechtigungen zu überprüfen. Diese Aufforderung soll eine potenzielle Endlosschleife unterbrechen, in der die App steckt, denn es gibt kaum oder überhaupt keinen Grund für eine App, vom Benutzer innerhalb einer Stunde zehn Token anzufordern.
Warning
Durch das Widerrufen aller Berechtigungen einer OAuth app werden alle SSH-Schlüssel gelöscht, die die Anwendung im Namen des Benutzers generiert hat, einschließlich der Bereitstellungsschlüssel.
Anleiten von Benutzern, ihren Zugriff zu überprüfen
Du kannst Autorisierungsinformationen für eine OAuth app verknüpfen, damit Benutzer*innen ihre Anwendungsautorisierungen überprüfen und widerrufen können.
Für diese Verknüpfung benötigen Sie die Client-ID (client_id
) Ihrer OAuth app, die Sie von GitHub beim Registrierung Ihrer Anwendung erhalten haben.
https://github.com/settings/connections/applications/:client_id
Tip
Weitere Informationen zu den Ressourcen, auf die deine OAuth app für einen Benutzer zugreifen kann, findest du unter Ermitteln von Ressourcen für einen Benutzer.
Problembehandlung
- Problembehandlung bei Autorisierungsanforderungsfehlern
- Problembehandlung bei Fehlern bei der Anforderung von OAuth-App-Zugriffstoken
- Geräteflussfehler
- Tokenablauf und Sperrung