Authentification App-only et jeton Bearer OAuth 2.0

​

Authentification App only et jeton Bearer OAuth 2.0

X offre aux applications la possibilité d’émettre des requêtes authentifiées pour le compte de l’application elle-même, plutôt que pour le compte d’un utilisateur spécifique. L’implémentation de X est basée sur le flux Client Credentials Grant de la spécification OAuth 2.

L’authentification uniquement au niveau de l’App n’inclut aucun contexte utilisateur et correspond à une forme d’authentification dans laquelle une application effectue des requêtes d’API en son propre nom. Cette méthode s’adresse aux développeurs qui ont simplement besoin d’un accès en lecture seule aux informations publiques. 

Vous pouvez effectuer une authentification App only en utilisant les clés d’API consommateur de votre App, ou en utilisant un App only Access Token (jeton Bearer). Cela signifie que les seules requêtes que vous pouvez effectuer vers une X API ne doivent pas nécessiter d’utilisateur authentifié.

Avec l’authentification App only, vous pouvez effectuer des actions telles que :

• Récupérer les timelines d’utilisateurs
• Accéder aux amis et abonnés de n’importe quel compte
• Accéder aux ressources de Listes
• Rechercher des Tweets

Veuillez noter que seuls OAuth 1.0a ou le flux OAuth 2.0 Authorization Code avec PKCE sont requis pour émettre des requêtes pour le compte des utilisateurs. La page de Référence de l’API décrit la méthode d’authentification requise pour utiliser une API. Vous aurez besoin d’une authentification utilisateur, avec contexte utilisateur, et d’un access token pour effectuer les actions suivantes :

• Publier des Tweets ou d’autres types de ressources
• Rechercher des utilisateurs
• Utiliser n’importe quel endpoint de géolocalisation
• Accéder aux Direct Messages ou aux identifiants du compte
• Récupérer les adresses e‑mail des utilisateurs

​

Flux d’authentification

Pour utiliser cette méthode, vous devez utiliser un Jeton d’accès App only (également appelé Jeton Bearer). Vous pouvez générer un Jeton d’accès App only (Jeton Bearer) en transmettant votre consumer key et votre secret via l’endpoint POST oauth2/token. 

Le flux d’authentification App only suit les étapes suivantes :

• Une application encode sa consumer key et son secret dans un ensemble d’identifiants spécifiquement encodés.
• Une application envoie une requête à l’endpoint POST oauth2/token pour échanger ces identifiants contre un Jeton d’accès App only.
• Lorsqu’elle accède à l’API REST, l’application utilise le Jeton d’accès App only pour s’authentifier.

Comme il n’est pas nécessaire de signer une requête, cette approche est beaucoup plus simple que le modèle OAuth 1.0a standard.

​

À propos de l’authentification App only

Les jetons sont des mots de passe

N’oubliez pas que la clé consommateur et le secret consommateur, ainsi que le jeton d’accès App only (Jeton Bearer) lui-même, permettent d’effectuer des requêtes au nom d’une application. Ces valeurs doivent être considérées comme aussi sensibles que des mots de passe et ne doivent pas être partagées ni diffusées à des tiers non approuvés.

SSL requis

Toutes les requêtes (à la fois pour obtenir et pour utiliser les jetons) doivent utiliser des endpoints HTTPS. Suivez les bonnes pratiques décrites dans Connecting to X API using TLS — les pairs doivent toujours être vérifiés.

Aucun contexte utilisateur

Lors de l’envoi de requêtes à l’aide de l’authentification App only, il n’existe pas de notion d’« utilisateur actuel ». Par conséquent, des endpoints comme POST statuses/update ne fonctionneront pas avec l’authentification App only. Consultez using OAuth pour plus d’informations sur l’envoi de requêtes au nom d’un utilisateur.

Limites de taux

Les applications disposent de deux types de pools de limites de taux.

Les requêtes effectuées au nom d’utilisateurs avec des jetons d’accès, également appelées contexte utilisateur, sont déduites d’un contexte de limites de taux différent de celui utilisé dans l’authentification App only. En d’autres termes, les requêtes effectuées au nom d’utilisateurs ne seront pas imputées aux limites de taux disponibles via l’authentification App only, et les requêtes effectuées via l’authentification App only ne seront pas imputées aux limites de taux utilisées dans l’authentification basée sur l’utilisateur.

En savoir plus sur les limites de taux de l’API et consulter les limites.

​

Émission de requêtes App only

Étape 1 : Encoder la consumer key et la consumer secret

Les étapes pour encoder la consumer key et la consumer secret d’une application en un ensemble d’identifiants permettant d’obtenir un Jeton Bearer sont :

1. Encoder la consumer key et la consumer secret en URL conformément à la RFC 1738. Notez qu’au moment de la rédaction, cela ne modifie en réalité ni la consumer key ni la consumer secret, mais cette étape doit tout de même être effectuée au cas où le format de ces valeurs changerait à l’avenir.
2. Concaténer la consumer key encodée, un caractère deux-points « : » et la consumer secret encodée en une seule chaîne de caractères.
3. Encoder en Base64 la chaîne issue de l’étape précédente.

Ci-dessous se trouvent des valeurs d’exemple montrant le résultat de cet algorithme. Notez que la consumer secret utilisée sur cette page est destinée à des fins de test et ne fonctionnera pas pour de vraies requêtes.

Consumer key	xvz1evFS4wEEPTGEFPHBog
Consumer secret	L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Consumer key encodée selon la RFC 1738 (inchangée)	xvz1evFS4wEEPTGEFPHBog
Consumer secret encodée selon la RFC 1738 (inchangée)	L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Identifiants du Jeton Bearer	xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg
Identifiants du Jeton Bearer encodés en Base64	:: eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==

Étape 2 : Obtenir un App only Access Token (Jeton Bearer)

La valeur calculée à l’étape 1 doit être échangée contre un App only Access Token en émettant une requête vers POST oauth2/token :

• La requête doit être une requête HTTP POST.
• La requête doit inclure un en-tête Authorization ayant pour valeur Basic <valeur encodée en Base64 à l’étape 1>.
• La requête doit inclure un en-tête Content-Type ayant pour valeur application/x-www-form-urlencoded;charset=UTF-8.
• Le corps de la requête doit être grant_type=client_credentials.

Exemple de requête (l’en-tête Authorization a été replié) :

POST /oauth2/token HTTP/1.1
Host: api.x.com
User-Agent: My X App v1.0.23
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip

grant\_type=client\_credentials

Si la requête est correctement formée, le serveur renvoie un corps de réponse encodé en JSON :

Exemple de réponse :

HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...
Content-Encoding: gzip
Content-Length: 140

{"token\_type":"bearer","access\_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

Les applications doivent vérifier que la valeur associée à la clé token_type de l’objet renvoyé est bearer. La valeur associée à la clé access_token est le Jeton d’accès App only (Jeton Bearer).

Notez qu’un seul Jeton d’accès App only est valide pour une application à la fois. L’envoi d’une autre requête avec les mêmes identifiants à /oauth2/token renverra le même jeton jusqu’à ce qu’il soit invalidé.

Étape 3 : Authentifier les requêtes d’API avec le Jeton d’accès App only (Jeton Bearer)

Le Jeton d’accès App only (Jeton Bearer) peut être utilisé pour envoyer des requêtes vers des endpoints d’API qui prennent en charge l’authentification App only. Pour utiliser le Jeton d’accès App, construisez une requête HTTPS normale et incluez un en-tête Authorization avec la valeur Bearer <base64 bearer token value from step 2>. Signing is not required.

Exemple de requête (l’en-tête Authorization a été reformaté sur plusieurs lignes) :

GET /1.1/statuses/user\_timeline.json?count=100&screen\_name=twitterapi HTTP/1.1
Host: api.x.com
User-Agent: My X App v1.0.23
Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAA
                      AAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Accept-Encoding: gzip

Invalidation d’un jeton d’accès App-only (Jeton Bearer)

Si un jeton d’accès App-only est compromis ou doit être invalidé pour une raison quelconque, effectuez un appel vers POST oauth2/invalidate_token.

Exemple de requête (l’en-tête Authorization a été coupé sur plusieurs lignes) :

POST /oauth2/invalidate_token HTTP/1.1
Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJn
                     NmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
User-Agent: My X App v1.0.23
Host: api.x.com
Accept: */*
Content-Length: 119
Content-Type: application/x-www-form-urlencoded

access_token=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

Exemple de réponse :

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 127
...

{"access_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

​

Cas d’erreur courants

Cette section décrit certaines erreurs fréquentes lors de la négociation et de l’utilisation de jetons Bearer. Sachez que toutes les réponses d’erreur possibles ne sont pas couvertes ici : restez attentif aux codes et réponses d’erreur non gérés.

Requêtes invalides pour obtenir ou révoquer un App only Access Token

Tentatives de :

• Obtenir un App only Access Token (Bearer Token) avec une requête invalide (par exemple, en omettant grant_type=client_credentials).
• Obtenir ou révoquer un App only Access Token (Bearer Token) avec des identifiants d’App invalides ou expirés.
• Invalider un App only Access Token (Bearer Token) incorrect ou déjà révoqué.
• Obtenir un App only Access Token (Bearer Token) trop fréquemment sur une courte période.

Auront pour effet :

HTTP/1.1 403 Forbidden
Content-Length: 105
Content-Type: application/json; charset=utf-8
...

{"errors":\[{"code":99,"label":"authenticity\_token\_error","message":"Impossible de vérifier vos identifiants"}\]}

​

La requête API contient un jeton d’accès App only (Jeton Bearer) invalide

L’utilisation d’un jeton d’accès incorrect ou révoqué pour effectuer des requêtes à l’API entraînera :

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 61
...

{"errors":\[{"message":"Invalid or expired token","code":89}\]}

​

Jeton d’accès App uniquement (Jeton Bearer) utilisé sur un endpoint qui ne prend pas en charge l’authentification App uniquement

Effectuer un appel vers un endpoint qui nécessite un contexte utilisateur (comme statuses/home_timeline) avec un jeton d’accès App uniquement (Jeton Bearer) produira :

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 91
...

{"errors":\[{"message":"Your credentials do not allow access to this resource","code":220}\]}