API Gateway:Utiliser l'authentification par résumé pour appeler une API

Les API utilisant l'authentification par résumé (AppKey et AppSecret) exigent que le client signe chaque requête. Les SDK d'API Gateway gèrent la signature automatiquement. Cette rubrique explique le processus de signature pour les implémentations clientes personnalisées.

API Gateway génère et vérifie les signatures de requête pour :

• Valider que les requêtes contiennent une signature correcte basée sur l'AppKey autorisé.

• Empêcher la falsification des requêtes lors de la transmission.

Les fournisseurs d'API créent des applications depuis la page Apps de la console API Gateway. Chaque application dispose d'une paire de clés de signature (AppKey et AppSecret). Une fois qu'un fournisseur a autorisé une application à appeler une API, les appelants utilisent cette paire de clés pour signer les requêtes. L'application peut appartenir au fournisseur ou à l'appelant.

Lorsqu'un client appelle une API, il signe la requête avec la paire de clés autorisée et ajoute l'AppKey ainsi que la signature à l'en-tête de la requête. API Gateway lit l'AppKey, récupère l'AppSecret correspondant et recalcule la signature. Si la signature calculée correspond à celle du client, la requête est transmise au service backend. Sinon, API Gateway renvoie une erreur.

API Gateway ne vérifie les signatures que pour les API dont l'option Security Authentication est définie sur Alibaba Cloud App.

3,1. Génération et vérification de la signature

3,1,1. Prérequis

L'appelant de l'API a obtenu la paire de clés de signature pour l'API cible.

• APP Key

• APP Secret

L'option Security Authentication de l'API cible est définie sur Alibaba Cloud App.

3,1,2. Génération de la signature côté client

Pour générer une signature :

1. Extrayez les données clés de la requête pour obtenir une chaîne de signature.

2. Chiffrez la chaîne de signature avec l'AppSecret pour produire une signature.

3. Ajoutez tous les en-têtes liés à la signature à la requête HTTP.

3,1,3. Vérification de la signature côté serveur

Pour vérifier une signature client :

1. Extrayez les données clés de la requête pour construire une chaîne de signature.

2. Lisez l'AppKey dans la requête et récupérez l'AppSecret correspondant.

3. Chiffrez la chaîne de signature avec l'AppSecret pour produire une signature.

4. Comparez la signature côté serveur avec la signature côté client issue de la requête.

3,2. Génération et transfert de la signature

3,2,1. Extraction d'une chaîne de signature

Extrayez les données clés de la requête HTTP et combinez-les dans une chaîne de signature selon le format suivant :

HTTPMethod
Accept
Content-MD5
Content-Type
Date
Headers
PathAndParameters

Ces champs sont séparés par \n. Si Headers est vide, omettez son \n. Pour les autres champs vides, conservez le \n. La signature est sensible à la casse. Chaque champ est extrait comme suit :

• HTTPMethod : méthode HTTP utilisée pour envoyer la requête (par exemple, POST). Doit être en majuscules.

• Accept : valeur de l'en-tête Accept. Peut rester vide, mais nous vous recommandons de le définir explicitement. Certains clients HTTP ont / par défaut, ce qui entraîne l'échec de la vérification de la signature.

• Content-MD5 : valeur de l'en-tête Content-MD5. Facultatif.

  • Calculé uniquement pour les requêtes dont le corps n'est pas de type Form. Si le client omet Content-MD5, API Gateway ignore la validation.

  • Exemple Java pour calculer Content-MD5 :

String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));

• Content-Type : valeur de l'en-tête Content-Type. Facultatif.

• Date : valeur de l'en-tête Date. Facultatif.

• Headers : en-têtes personnalisés à inclure dans la signature. Règles de concaténation :

  • Triez les clés d'en-tête par ordre alphabétique et concaténez-les comme suit :

  HeaderKey1 + ":" + HeaderValue1 + "\n" +
  HeaderKey2 + ":" + HeaderValue2 + "\n" +
  ...
  HeaderKeyN + ":" + HeaderValueN + "\n"

  • Si la valeur d'un en-tête est vide, utilisez HeaderKey + ":" + "\n" et conservez la clé ainsi que les deux-points (:).

  • Placez les clés d'en-tête utilisées pour la signature dans l'en-tête X-Ca-Signature-Headers, séparées par des virgules (,).

  • Les en-têtes suivants ne peuvent pas être utilisés pour le calcul de la signature : X-Ca-Signature, X-Ca-Signature-Headers, Accept, Content-MD5, Content-Type et Date.

• PathAndParameters : inclut tous les paramètres Path, Query et Form.

  Path + "?" + Key1 + "=" + Value1 + "&" + Key2 + "=" + Value2 + ... "&" + KeyN + "=" + ValueN

  • Triez les clés des paramètres Query et Form par ordre alphabétique, puis concaténez-les comme indiqué ci-dessus.

  • Si les paramètres Query et Form sont vides, utilisez uniquement le Path sans ajouter de point d'interrogation (?).

  • Si la valeur d'un paramètre est vide, utilisez uniquement la clé pour la signature.

  • Pour les paramètres de tableau ayant la même clé mais des valeurs différentes, seule la première valeur est utilisée pour la signature.

Exemple de requête HTTP :

POST /http2test/test?param1=test HTTP/1.1
host:api.aliyun.com
accept:application/json; charset=utf-8
ca_version:1
content-type:application/x-www-form-urlencoded; charset=utf-8
x-ca-timestamp:1525872629832
date:Wed, 09 May 2018 13:30:29 GMT+00:00
user-agent:ALIYUN-ANDROID-DEMO
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
content-length:33
username=xiaoming&password=123456789

Chaîne de signature générée pour cette requête :

POST
application/json; charset=utf-8
application/x-www-form-urlencoded; charset=utf-8
Wed, 09 May 2018 13:30:29 GMT+00:00
x-ca-key:203753385
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
x-ca-signature-method:HmacSHA256
x-ca-timestamp:1525872629832
/http2test/test?param1=test&password=123456789&username=xiaoming

3,2,2. Calcul de la signature

Après avoir combiné les données clés dans une chaîne de signature, chiffrez et encodez-la pour produire la signature finale. Algorithmes pris en charge :

• HmacSHA256

• HmacSHA1

Exemples de chiffrement, où stringToSign est la chaîne de signature et appSecret est l'AppSecret :

Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] appSecretBytes = appSecret.getBytes(Charset.forName("UTF-8"));
hmacSha256.init(new SecretKeySpec(appSecretBytes, 0, appSecretBytes.length, "HmacSHA256"));
byte[] md5Result = hmacSha256.doFinal(stringToSign.getBytes(Charset.forName("UTF-8")));
String signature = Base64.encodeBase64String(md5Result);

Mac hmacSha1 = Mac.getInstance("HmacSHA1");
byte[] appSecretBytes = appSecret.getBytes(Charset.forName("UTF-8"));
hmacSha1.init(new SecretKeySpec(appSecretBytes, 0, appSecretBytes.length, "HmacSHA1"));
byte[] md5Result = hmacSha1.doFinal(stringToSign.getBytes(Charset.forName("UTF-8")));
String signature = Base64.encodeBase64String(md5Result);

La StringToSign est décodée en tant que tableau d'octets UTF-8, chiffrée, puis encodée en Base64 pour produire la signature finale.

3,2,3. Transfert de la signature

Incluez les en-têtes suivants dans les requêtes envoyées à API Gateway :

• x-ca-key : AppKey. Ce paramètre est obligatoire.

• x-ca-signature-method : méthode de signature. Ce paramètre est facultatif. Valeurs valides : HmacSHA256 et HmacSHA1. Valeur par défaut : HmacSHA256.

• X-Ca-Signature-Headers : clés de tous les en-têtes de signature. Ce paramètre est facultatif. Séparez plusieurs clés par des virgules (,).

• X-Ca-Signature : signature. Ce paramètre est obligatoire.

Exemple de requête HTTP signée :

POST /http2test/test?param1=test HTTP/1.1
host:api.aliyun.com
accept:application/json; charset=utf-8
ca_version:1
content-type:application/x-www-form-urlencoded; charset=utf-8
x-ca-timestamp:1525872629832
date:Wed, 09 May 2018 13:30:29 GMT+00:00
user-agent:ALIYUN-ANDROID-DEMO
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
x-ca-key:203753385
x-ca-signature-method:HmacSHA256
x-ca-signature-headers:x-ca-timestamp,x-ca-key,x-ca-nonce,x-ca-signature-method
x-ca-signature:xfX+bZxY2yl7EB/qdoDy9v/uscw3Nnj1pgoU+Bm6xdM=
content-length:33
username=xiaoming&password=123456789

3,3. Dépannage

Si la vérification de la signature échoue, API Gateway renvoie la StringToSign côté serveur dans l'en-tête de réponse X-Ca-Error-Message. Comparez-la avec la StringToSign côté client pour identifier les divergences.

Si les deux chaînes correspondent, vérifiez l'AppSecret utilisé pour la signature.

Les en-têtes HTTP ne prennent pas en charge les sauts de ligne. Les sauts de ligne dans la StringToSign sont remplacés par des dièses (#).

errorMessage:  Invalid Signature, Server StringToSign:`GET#application/json##application/json##X-Ca-Key:200000#X-Ca-Timestamp:1589458000000#/app/v1/config/keys?keys=TEST`

Exemple de chaîne de signature côté serveur :

GET
application/json
application/json
X-Ca-Key:200000
X-Ca-Timestamp:1589458000000
/app/v1/config/keys?keys=TEST