Créer une signature

​

Création d’une signature

Cette page explique comment générer une signature OAuth 1.0a HMAC-SHA1 pour une requête HTTP. Cette signature pourra être transmise à la X API dans le cadre d’une requête autorisée, comme expliqué dans Autoriser une requête.

La requête utilisée pour illustrer la signature est une requête POST vers https://api.x.com/1.1/statuses/update.json. La requête brute ressemble à ceci :

POST /1.1/statuses/update.json?include_entities=true HTTP/1.1
Accept: */*
Connection: close
User-Agent: OAuth gem v0.4.4
Content-Type: application/x-www-form-urlencoded
Content-Length: 76
Host: api.x.com

status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21

Collecte de la méthode de requête et de l’URL

Pour produire une signature, commencez par déterminer la méthode HTTP et l’URL de la requête. Ces deux éléments sont connus lors de la création de la requête, ils sont donc faciles à obtenir.

La méthode de requête sera presque toujours GET ou POST pour les requêtes X API.

Méthode HTTP	POST

L’URL de base est l’URL vers laquelle la requête est envoyée, sans la chaîne de requête (query string) ni les paramètres de hash. Il est important d’utiliser le bon protocole ici, donc assurez-vous que la partie « https:// » de l’URL correspond à la requête effectivement envoyée à l’API.

URL de base	https://api.x.com/1.1/statuses/update.json

​

Collecte des paramètres

Ensuite, regroupez tous les paramètres inclus dans la requête. Ces paramètres supplémentaires se trouvent à deux emplacements : l’URL (dans la chaîne de requête) et le corps de la requête. L’exemple de requête inclut un seul paramètre à chacun de ces emplacements :

POST /1.1/statuses/update.json?include_entities=true HTTP/1.1
Accept: */*
Connection: close
User-Agent: OAuth gem v0.4.4
Content-Type: application/x-www-form-urlencoded
Content-Length: 76
Host: api.x.com

status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21

Une requête HTTP comporte des paramètres encodés dans l’URL, mais vous devez récupérer les valeurs brutes. En plus des paramètres de requête, chaque paramètre oauth_* doit être inclus dans la signature, récupérez-les donc également. Voici les paramètres issus de l’autorisation d’une requête :

status	Hello Ladies + Gentlemen, a signed OAuth request!
include_entities	true
oauth_consumer_key	xvz1evFS4wEEPTGEFPHBog
oauth_nonce	kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg
oauth_signature_method	HMAC-SHA1
oauth_timestamp	1318622958
oauth_token	370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
oauth_version	1.0

Ces valeurs doivent être encodées en une seule chaîne, qui sera utilisée ultérieurement. Le processus de construction de la chaîne est très strict :

1. Encodage en pourcentage de chaque clé et valeur qui sera signée.
2. Triez la liste des paramètres par ordre alphabétique [1] selon la clé encodée [2].
3. Pour chaque paire clé/valeur :
4. Ajoutez la clé encodée à la chaîne de sortie.
5. Ajoutez le caractère “=” à la chaîne de sortie.
6. Ajoutez la valeur encodée à la chaîne de sortie.
7. S’il reste d’autres paires clé/valeur, ajoutez un caractère “&” à la chaîne de sortie.  

[1] La spécification OAuth indique de trier lexicographiquement, ce qui correspond au tri alphabétique par défaut de nombreuses bibliothèques.

[2] En cas de deux paramètres ayant la même clé encodée, la spécification OAuth indique de poursuivre le tri en se basant sur la valeur. Toutefois, X n’accepte pas les clés dupliquées dans les requêtes API.  

Chaîne de paramètres

La chaîne de paramètres suivante sera produite en répétant ces étapes avec les paramètres collectés ci-dessus :

status	Hello Ladies + Gentlemen, a signed OAuth request!
include_entities	true
oauth_consumer_key	xvz1evFS4wEEPTGEFPHBog
oauth_nonce	kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg
oauth_signature_method	HMAC-SHA1
oauth_timestamp	1318622958
oauth_token	370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
oauth_version	1.0

​

Création de la chaîne de base de la signature

Les trois valeurs collectées jusqu’à présent doivent être concaténées pour former une seule chaîne, à partir de laquelle la signature sera générée. La spécification OAuth appelle cela la chaîne de base de la signature.

Pour encoder la méthode HTTP, l’URL de base et la chaîne de paramètres en une seule chaîne :

1. Convertissez la méthode HTTP en majuscules et affectez cette valeur à la chaîne de sortie.
2. Ajoutez le caractère « & » à la chaîne de sortie.
3. Pourcentagez (percent-encode) l’URL et ajoutez-la à la chaîne de sortie.
4. Ajoutez le caractère « & » à la chaîne de sortie.
5. Pourcentagez (percent-encode) la chaîne de paramètres et ajoutez-la à la chaîne de sortie.  

Cela produira la chaîne de base de la signature suivante :

POST&https%3A%2F%2Fapi.x.com%2F1.1%2Fstatuses%2Fupdate.json&include\_entities%3Dtrue%26oauth\_consumer\_key%3Dxvz1evFS4wEEPTGEFPHBog%26oauth\_nonce%3DkYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg%26oauth\_signature\_method%3DHMAC-SHA1%26oauth\_timestamp%3D1318622958%26oauth\_token%3D370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb%26oauth_version%3D1.0%26status%3DHello%2520Ladies%2520%252B%2520Gentlemen%252C%2520a%2520signed%2520OAuth%2520request%2521

Assurez-vous d’encoder la chaîne de paramètres en pourcentage. La chaîne de base de la signature doit contenir exactement 2 caractères esperluette « & ». Les signes pourcent « % » dans la chaîne de paramètres doivent être encodés sous la forme %25 dans la chaîne de base de la signature.

​

Obtenir une clé de signature

Les derniers éléments à collecter sont des secrets qui identifient l’X App à l’origine de la requête, ainsi que l’utilisateur au nom duquel la requête est effectuée. Il est très important de noter que ces valeurs sont extrêmement sensibles et ne doivent jamais être partagées.

La valeur qui identifie votre App auprès de X s’appelle le consumer secret et se trouve dans le developer portal, sur la page des détails de l’App. Elle sera la même pour chaque requête envoyée par votre X App.

Consumer secret	kAcSOqF21Fu85e7zjz7ZN2U4ZRhfV3WpwPAoE3Z7kBw

La valeur qui identifie le compte pour lequel votre application agit s’appelle le OAuth token secret. Cette valeur peut être obtenue de plusieurs façons, toutes décrites dans obtaining access tokens.

OAuth token secret	LswwdoUaIvS8ltyTt5jkRh4J50vUPVVHtR2YPi5kE

Encore une fois, il est très important de garder ces valeurs strictement privées à votre application. Si vous pensez qu’elles ont été compromises, régénérez vos tokens (les tokens présentés sur cette page ont été marqués comme invalides pour des requêtes réelles).

Ces deux valeurs doivent être combinées pour former une clé de signature qui sera utilisée pour générer la signature. La clé de signature est simplement le token secret percent encoded :

Notez qu’il existe certains parcours, par exemple lors de l’obtention d’un request token, où le token secret n’est pas encore connu. Dans ce cas, la clé de signature doit être composée du consumer secret percent encoded suivi d’un caractère esperluette « & ».

Signing key	kAcSOqF21Fu85e7zjz7ZN2U4ZRhfV3WpwPAoE3Z7kBw&LswwdoUaIvS8ltyTt5jkRh4J50vUPVVHtR2YPi5kE

​

Calcul de la signature

Enfin, la signature est calculée en transmettant la chaîne de base de signature et la clé de signature à l’algorithme de hachage HMAC-SHA1. Les détails de l’algorithme sont présentés dans la fonction hash_hmac.

La sortie de la fonction de signature HMAC est une chaîne binaire. Celle-ci doit être encodée en base64 pour produire la chaîne de signature. Par exemple, la sortie, compte tenu de la chaîne de base et de la clé de signature indiquées sur cette page, est 2E CF 77 84 98 99 6D 0D DA 90 5D C7 17 7C 75 07 3F 3F CD 4E. Cette valeur, une fois convertie en base64, constitue la signature OAuth pour cette requête :

Signature OAuth	Ls93hJiZbQ3akF3HF3x1Bz8/zU4=