Flux de code d’autorisation OAuth 2.0 avec PKCE

Flux de code d’autorisation OAuth 2.0 avec PKCE

Introduction

OAuth 2.0 est un protocole d’autorisation standard du secteur qui permet un contrôle plus précis sur le périmètre d’accès d’une application et sur les flux d’autorisation sur plusieurs appareils. OAuth 2.0 vous permet de choisir des périmètres d’accès (scopes) fins et spécifiques, qui vous donnent des autorisations précises pour le compte d’un utilisateur. 

Pour activer OAuth 2.0 pour votre App, vous devez l’activer dans les paramètres d’authentification de votre App, accessibles dans la section App settings de la Console de développement.

Pendant combien de temps mes identifiants resteront-ils valides ?

Par défaut, le jeton d’accès que vous créez via le flux d’autorisation Authorization Code Flow with PKCE n’est valide que pendant deux heures, sauf si vous avez utilisé la portée offline.access.

Jetons d’actualisation

Les jetons d’actualisation permettent à une application d’obtenir un nouveau jeton d’accès sans solliciter l’utilisateur, via le flux d’actualisation.

Si le scope offline.access est appliqué, un jeton d’actualisation OAuth 2.0 sera émis. Grâce à ce jeton d’actualisation, vous pouvez obtenir un jeton d’accès. Si ce scope n’est pas transmis, nous ne générerons pas de jeton d’actualisation.

Voici un exemple de requête à envoyer pour utiliser un jeton d’actualisation afin d’obtenir un nouveau jeton d’accès :

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

Paramètres de l’App

Vous pouvez configurer les paramètres d’authentification de votre App pour utiliser OAuth 1.0a ou OAuth 2.0. Vous pouvez également autoriser une App à utiliser à la fois OAuth 1.0a et OAuth 2.0.

OAuth 2.0 ne peut être utilisé qu’avec X API v2. Si vous avez sélectionné OAuth 2.0, vous verrez un Client ID dans la section Keys and Tokens de votre App. 

Clients confidentiels

Les clients confidentiels peuvent conserver des identifiants de façon sécurisée sans les exposer à des tiers non autorisés et s’authentifier de manière sécurisée auprès du serveur d’autorisation, ce qui permet de garder votre Client Secret en sécurité. Les clients publics, qui s’exécutent généralement dans un navigateur ou sur un appareil mobile, ne peuvent pas utiliser vos Client Secrets. Si vous sélectionnez un type d’App qui est un client confidentiel, un Client Secret vous sera fourni. 

Si vous avez sélectionné un type de client qui est un client confidentiel dans la Console de développement, vous verrez également un Client Secret. Vos options sont Native App, Single page App, Web App, Automated App ou bot. Les Native App et Single page Apps sont des clients publics, et les Web App et Automated App ou bots sont des clients confidentiels.

Vous n’avez pas besoin de client id pour les clients confidentiels avec un en-tête Authorization valide. Vous devez toujours inclure le Client Id dans le corps des requêtes avec un client public. 

Scopes

Les scopes vous permettent de définir un accès granulaire pour votre App afin qu’elle ne dispose que des autorisations dont elle a besoin. Pour en savoir plus sur la correspondance entre les scopes et les endpoints, consultez notre guide de correspondance d’authentification.

Scope	Description
tweet.read	Tous les Tweets que vous pouvez voir, y compris les Tweets de comptes protégés.
tweet.write	Tweeter et Retweeter en votre nom.
tweet.moderate.write	Masquer et réafficher les réponses à vos Tweets.
users.email	Adresse e-mail d’un utilisateur authentifié.
users.read	Tout compte que vous pouvez voir, y compris les comptes protégés.
follows.read	Les personnes qui vous suivent et les personnes que vous suivez.
follows.write	Suivre et ne plus suivre des personnes en votre nom.
offline.access	Rester connecté à votre compte jusqu’à ce que vous révoquiez l’accès.
space.read	Tous les Espaces que vous pouvez voir.
mute.read	Comptes que vous avez mis en sourdine.
mute.write	Mettre en sourdine et réactiver des comptes en votre nom.
like.read	Tweets que vous avez aimés et mentions « J’aime » que vous pouvez voir.
like.write	Ajouter et retirer des mentions « J’aime » sur des Tweets en votre nom.
list.read	Listes, membres de listes et abonnés aux listes que vous avez créées ou dont vous êtes membre, y compris les listes privées.
list.write	Créer et gérer des listes en votre nom.
block.read	Comptes que vous avez bloqués.
block.write	Bloquer et débloquer des comptes en votre nom.
bookmark.read	Récupérer les Tweets ajoutés aux signets par un utilisateur authentifié.
bookmark.write	Ajouter des Tweets aux signets et en retirer.
media.write	Téléverser des médias.

Limites de taux

Dans l’ensemble, les limites de taux sont identiques à celles appliquées lors de l’authentification avec OAuth 1.0a, à l’exception de la recherche de Tweets et de la recherche d’utilisateurs. Nous portons la limite par App de 300 à 900 requêtes par tranche de 15 minutes lorsque vous utilisez OAuth 2.0 pour la recherche de Tweets et la recherche d’utilisateurs. Pour en savoir plus, consultez notre documentation sur les limites de taux.

Types de flux d’autorisation

Pour ce lancement initial, nous proposons uniquement le code d’autorisation avec PKCE et le jeton d’actualisation comme types de flux d’autorisation pris en charge. Nous pourrons proposer d’autres types de flux d’autorisation à l’avenir.

Flux OAuth 2.0

OAuth 2.0 utilise un flux similaire au flux que nous utilisons actuellement pour OAuth 1.0a. Vous pouvez consulter un schéma et une explication détaillée dans notre documentation sur ce sujet. 

Glossaire

Terme	Description
Grant types	La spécification OAuth définit plusieurs types de « grant » pour différents cas d’usage, ainsi qu’un cadre pour en créer de nouveaux. Parmi eux : authorization code, client credentials, device code et refresh token.
Confidential client	Les clients confidentiels sont des applications qui peuvent s’authentifier de manière sécurisée auprès du serveur d’autorisation, par exemple en conservant leur client secret enregistré en sécurité.
Public client	Les clients publics ne peuvent pas utiliser de client secrets enregistrés, comme les applications exécutées dans un navigateur ou sur un appareil mobile.
Authorization code flow	Flux utilisé par les clients confidentiels et publics pour échanger un code d’autorisation contre un access token.
PKCE	Extension de l’authorization code flow qui empêche plusieurs types d’attaques et permet d’effectuer l’échange OAuth de manière sécurisée depuis des clients publics.
Client ID	Peut être trouvé dans la section des clés et des jetons de la Console de développement sous l’en-tête « Client ID ». Si vous ne le voyez pas, veuillez contacter directement notre équipe. Le Client ID sera nécessaire pour générer l’URL d’autorisation.
Redirect URI	Votre URL de rappel (callback URL). Vous devrez utiliser la validation de correspondance exacte.
Authorization code	Permet à une application d’appeler les API au nom des utilisateurs. Appelé auth_code. L’auth_code a une durée de validité de 30 secondes à compter du moment où le propriétaire de l’App reçoit un auth_code approuvé de l’utilisateur. Vous devrez l’échanger contre un access token dans les 30 secondes, faute de quoi l’auth_code expirera.
Access token	Les access tokens sont les jetons que les applications utilisent pour effectuer des requêtes d’API au nom d’un utilisateur.
Refresh token	Permet à une application d’obtenir un nouvel access token sans solliciter l’utilisateur, via le refresh token flow.
Client Secret	Si vous avez sélectionné un type d’App qui est un confidential client, un « Client Secret » vous sera fourni sous « Client ID » dans la section des clés et des jetons de votre App.

Paramètres

Pour construire une URL d’autorisation OAuth 2.0, vous devez vous assurer que les paramètres suivants sont présents dans l’URL d’autorisation. 

Paramètre	Description
response_type	Vous devez indiquer qu’il s’agit d’un code avec le mot « code ».
client_id	Vous pouvez le trouver dans la Console de développement sous l’en-tête « Client ID ».
redirect_uri	Votre URL de rappel. Cette valeur doit correspondre à l’une des URLs de rappel définies dans les paramètres de votre App. Pour OAuth 2.0, vous devez disposer d’une validation de correspondance exacte pour votre URL de rappel.
state	Une chaîne aléatoire que vous fournissez pour vous protéger contre les attaques CSRF.  La longueur de cette chaîne peut aller jusqu’à 500 caractères.
code_challenge	Un paramètre PKCE, un secret aléatoire propre à chaque requête que vous effectuez.
code_challenge_method	Indique la méthode que vous utilisez pour effectuer une requête (S256 OU plain).

URL d’autorisation

Avec OAuth 2.0, vous créez une URL d’autorisation que vous pouvez utiliser pour permettre à un utilisateur de s’authentifier via un flux d’authentification, similaire à « Se connecter avec X ». 

Voici un exemple de l’URL que vous allez créer :

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

Vous devrez utiliser l’encodage approprié pour que cette URL fonctionne. Veillez à consulter notre documentation sur l’encodage pourcentuel.