Autorisieren von OAuth-Apps

Die OAuth-Implementierung von GitHub Enterprise Server 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

Der Webanwendungsfluss zum Autorisieren von Benutzer*innen für deine App lautet wie folgt:

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

1. Anfordern der GitHub-Identität eines Benutzers

GET http(s)://HOSTNAME/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 Enterprise Server 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 http(s)://HOSTNAME/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 Enterprise Server für Ihre OAuth app erhalten haben.
client_secret	string	Erforderlich	Der geheime Clientschlüssel, den Sie von GitHub Enterprise Server 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 http(s)://HOSTNAME/api/v3/user

In curl können Sie beispielsweise den Autorisierungsheader wie folgt festlegen:

curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/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 Ihrer App finden Sie unter Ändern einer GitHub-App-Registrierung für GitHub Apps und Ändern einer OAuth-App für OAuth apps.

Übersicht über den Gerätefluss

1. 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.
2. Die App fordert den Benutzer auf, einen Benutzerüberprüfungscode bei http(s)://HOSTNAME/login/device einzugeben.
3. 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 http(s)://HOSTNAME/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 Enterprise Server 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%2FHOSTNAME%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: http(s)://HOSTNAME/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 http(s)://HOSTNAME/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": "http(s)://HOSTNAME/login/device",
  "expires_in": 900,
  "interval": 5
}

Accept: application/xml
<OAuth>
  <device_code>3584d83530557fdd1f46af8289938c8ef79f9dc5</device_code>
  <user_code>WDJB-MJHT</user_code>
  <verification_uri>http(s)://HOSTNAME/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 http(s)://HOSTNAME/login/device einzugeben.

Schritt 3: App fragt GitHub ab, um zu überprüfen, ob der Benutzer das Gerät autorisiert hat

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

Deine App stellt Geräteautorisierungsanforderungen, die POST http(s)://HOSTNAME/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 finden Sie unter Grenzwerte 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 http(s)://HOSTNAME/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 Enterprise Server für Ihre OAuth app erhalten haben.
device_code	string	Erforderlich. Die von der POST http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 finden Sie unter „Gerätefluss.“

Weitere Informationen finden Sie unter OAuth 2.0-Geräteautorisierungsgewährung.

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.

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.

http(s)://HOSTNAME/settings/connections/applications/:client_id

Problembehandlung

• Problembehandlung bei Autorisierungsanforderungsfehlern
• Problembehandlung bei Fehlern bei der Anforderung von OAuth-App-Zugriffstoken
• Geräteflussfehler
• Tokenablauf und Sperrung

Weiterführende Themen

• Informationen zur Authentifizierung für GitHub