OAuth-2.0-Autorisierungscode-Flow mit PKCE

​

OAuth 2.0 Authorization Code Flow mit PKCE

​

Einführung

OAuth 2.0 ist ein branchenüblicher Autorisierungsstandard, der mehr Kontrolle über den Scope einer Anwendung sowie Autorisierungsabläufe über mehrere Geräte hinweg ermöglicht. Mit OAuth 2.0 können Sie feingranulare Scopes auswählen, die Ihnen bestimmte Berechtigungen im Namen eines Nutzers gewähren.

Um OAuth 2.0 in Ihrer App zu aktivieren, müssen Sie es in den Authentifizierungseinstellungen Ihrer App aktivieren. Diese finden Sie im Bereich App-Einstellungen des Entwicklerportals.

​

Wie lange bleiben meine Anmeldedaten gültig?  

Standardmäßig bleibt das access token, das Sie über den Authorization Code Flow mit PKCE erstellen, nur zwei Stunden gültig, es sei denn, Sie haben den offline.access Scope verwendet.

​

Refresh Tokens

Refresh Tokens ermöglichen es einer Anwendung, über den Refresh-Token-Flow ein neues access token zu erhalten, ohne den Nutzer zur Interaktion aufzufordern.

Wenn der Scope offline.access angewendet wird, wird ein OAuth 2.0 Refresh Token ausgestellt. Mit diesem Refresh Token erhalten Sie ein access token. Wenn dieser Scope nicht übergeben wird, erzeugen wir keinen Refresh Token.

Ein Beispiel für die Anfrage, mit der Sie einen Refresh Token verwenden, um ein neues access token zu erhalten, ist wie folgt:

POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=bWRWa3gzdnk3WHRGU1o0bmRRcTJ5VUxWX1lZTDdJSUtmaWcxbTVxdEFXcW5tOjE2MjIxNDc3NDM5MTQ6MToxOnJ0OjE' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ

​

App-Einstellungen

Sie können die Authentifizierungseinstellungen Ihrer App auf OAuth 1.0a oder OAuth 2.0 festlegen. Sie können Ihre App auch so konfigurieren, dass sie sowohl OAuth 1.0a als auch OAuth 2.0 verwendet.

OAuth 2.0 kann nur mit der X API v2 verwendet werden. Wenn Sie OAuth 2.0 ausgewählt haben, wird im Bereich Keys und Tokens Ihrer App eine Client-ID angezeigt. 

​

Vertrauliche Clients

Vertrauliche Clients können Anmeldedaten sicher speichern, ohne sie unbefugten Parteien offenzulegen, und sich sicher beim Autorisierungsserver authentifizieren; dabei bleibt Ihr Client Secret geschützt. Öffentliche Clients laufen hingegen üblicherweise in einem Browser oder auf einem mobilen Gerät und können Ihre Client Secrets nicht verwenden. Wenn Sie einen App-Typ auswählen, der ein vertraulicher Client ist, erhalten Sie ein Client Secret. 

Wenn Sie im Entwicklerportal einen Client-Typ ausgewählt haben, der ein vertraulicher Client ist, sehen Sie ebenfalls ein Client Secret. Ihre Optionen sind Native App, Single Page App, Web App, Automated App oder Bot. Native Apps und Single Page Apps sind öffentliche Clients, während Web Apps sowie Automated Apps oder Bots vertrauliche Clients sind.

Für vertrauliche Clients mit einem gültigen Authorization Header benötigen Sie keine id. Bei Anfragen mit einem öffentlichen Client müssen Sie die id dennoch im Body angeben. 

​

Scopes

Scopes ermöglichen es Ihnen, den Zugriff für Ihre App granular festzulegen, sodass Ihre App nur die benötigten Berechtigungen hat. Weitere Informationen darüber, welche Scopes welchen endpoints zugeordnet sind, finden Sie in unserem Authentication-Mapping-Leitfaden.

Scope	Beschreibung
tweet.read	Alle Tweets, die Sie sehen können, einschließlich Tweets von geschützten Accounts.
tweet.write	Tweets und Retweets in Ihrem Namen erstellen.
tweet.moderate.write	Antworten auf Ihre Tweets ausblenden und wieder einblenden.
users.email	E-Mail-Adresse eines authentifizierten Nutzers.
users.read	Jeder Account, den Sie sehen können, einschließlich geschützter Accounts.
follows.read	Personen, die Ihnen folgen, und Personen, denen Sie folgen.
follows.write	Personen in Ihrem Namen folgen und entfolgen.
offline.access	Mit Ihrem Account verbunden bleiben, bis Sie den Zugriff widerrufen.
space.read	Alle Spaces, die Sie sehen können.
mute.read	Accounts, die Sie stummgeschaltet haben.
mute.write	Accounts in Ihrem Namen stumm- und wieder einschalten.
like.read	Tweets, die Sie geliked haben, und likes, die Sie sehen können.
like.write	Tweets in Ihrem Namen liken und likes entfernen.
list.read	Lists, Listenmitglieder und Follower von Lists, die Sie erstellt haben oder bei denen Sie Mitglied sind, einschließlich privater Lists.
list.write	Lists in Ihrem Namen erstellen und verwalten.
block.read	Accounts, die Sie blockiert haben.
block.write	Accounts in Ihrem Namen blockieren und die Blockierung aufheben.
bookmark.read	Bookmarked Tweets eines authentifizierten Nutzers abrufen.
bookmark.write	Bookmarks für Tweets hinzufügen und Bookmarks entfernen.
media.write	Medien hochladen.

​

Rate Limits

Weitgehend entsprechen die Rate Limits denen bei der Authentifizierung mit OAuth 1.0a, mit Ausnahme von Tweets Lookup und Users Lookup. Für Tweet Lookup und Nutzer Lookup erhöhen wir das pro-App-Limit bei Verwendung von OAuth 2.0 von 300 auf 900 Anfragen pro 15 Minuten. Weitere Informationen finden Sie in unserer Dokumentation zu Rate Limits.

​

Grant-Typen

Für diese erste Version unterstützen wir nur den Authorization Code mit PKCE sowie den Refresh Token als Grant-Typen. Weitere Grant-Typen könnten in Zukunft hinzukommen.

​

OAuth 2.0 Flow

OAuth 2.0 verwendet einen ähnlichen Ablauf wie den, den wir derzeit für OAuth 1.0a nutzen. Ein Diagramm und eine ausführliche Erläuterung finden Sie in unserer Dokumentation zu diesem Thema. 

​

Glossar

Begriff	Beschreibung
Grant-Typen	Das OAuth-Framework definiert mehrere Grant-Typen für unterschiedliche Anwendungsfälle sowie einen Rahmen zur Erstellung neuer Grant-Typen. Beispiele sind Authorization Code, Client Credentials, Device Code und Refresh Token.
Confidential Client	Clients sind Anwendungen, die sich sicher beim Authorization Server authentifizieren können, zum Beispiel indem sie ihr registriertes Client Secret vertraulich aufbewahren.
Public Client	Clients, die keine registrierten Client Secrets verwenden können, etwa Anwendungen, die in einem Browser oder auf einem mobilen Gerät laufen.
Authorization Code Flow	Wird sowohl von Confidential als auch von Public Clients verwendet, um einen Authorization Code gegen ein access token auszutauschen.
PKCE	Eine Erweiterung des Authorization Code Flow, um verschiedene Angriffe zu verhindern und den OAuth-Austausch aus Public Clients heraus sicher durchzuführen.
Client ID	Zu finden im Bereich Keys und Tokens des Entwicklerportal unter der Überschrift „Client ID“. Wenn Sie diese nicht sehen, setzen Sie sich bitte direkt mit unserem Team in Verbindung. Die Client ID wird benötigt, um die Authorize-URL zu generieren.
Redirect URI	Ihre Callback-URL. Sie benötigen eine Exact-Match-Validierung.
Authorization Code	Ermöglicht es einer Anwendung, APIs im Namen von Nutzern aufzurufen. Bekannt als auth_code. Der auth_code hat ein Zeitlimit von 30 Sekunden, nachdem der App-Inhaber einen genehmigten auth_code vom Nutzer erhalten hat. Sie müssen ihn innerhalb von 30 Sekunden gegen ein access token austauschen, sonst läuft der auth_code ab.
Access Token	Access Tokens sind die Token, die Anwendungen verwenden, um API-Anfragen im Namen eines Nutzers zu stellen.
Refresh Token	Ermöglicht es einer Anwendung, ohne Benutzeraufforderung über den Refresh-Token-Flow ein neues access token zu erhalten.
Client Secret	Wenn Sie einen App-Typ ausgewählt haben, der ein Confidential Client ist, erhalten Sie unter „Client ID“ im Bereich Keys und Tokens Ihrer App ein „Client Secret“.

​

Parameter

Um eine OAuth 2.0-Autorisierungs-URL zu erstellen, stellen Sie sicher, dass die folgenden Parameter in der Autorisierungs-URL enthalten sind.

Parameter	Beschreibung
response_type	Geben Sie mit dem Wort „code“ an, dass es sich um einen Code handelt.
client_id	Im Entwicklerportal unter der Überschrift „Client ID“ zu finden.
redirect_uri	Ihre Callback-URL. Dieser Wert muss einer der in den Einstellungen Ihrer App definierten Callback-URLs entsprechen. Für OAuth 2.0 ist für Ihre Callback-URL eine Exact-Match-Validierung erforderlich.
state	Eine zufällige Zeichenfolge, die Sie bereitstellen, um sich gegen CSRF-Angriffe abzusichern. Die Länge dieser Zeichenfolge kann bis zu 500 Zeichen betragen.
code_challenge	Ein PKCE-Parameter, ein zufälliges Geheimnis für jede von Ihnen gesendete Anfrage.
code_challenge_method	Gibt die Methode an, die Sie für die Anfrage verwenden (S256 oder plain).

​

Authorize URL 

Mit OAuth 2.0 erstellen Sie eine Authorize-URL, über die sich ein Nutzer über einen Authentifizierungsablauf anmelden kann, ähnlich wie „Bei X anmelden“. 

Ein Beispiel für die URL, die Sie erstellen, lautet wie folgt:

https://x.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https://www.example.com&scope=tweet.read%20users.read%20account.follows.read%20account.follows.write&state=state&code_challenge=challenge&code_challenge_method=plain

Damit diese URL funktioniert, muss sie korrekt kodiert sein. Lesen Sie unbedingt unsere Dokumentation zur Prozentkodierung.