API Gateway:Plug-in de signature backend

1. Qu'est-ce qu'une signature backend

Une signature backend (anciennement appelée clé de signature) est une paire clé/secret que vous créez. Elle fonctionne comme un identifiant que vous émettez pour la passerelle. Lorsque la passerelle envoie une requête à votre service backend, elle calcule une signature et la transmet avec la requête. Votre service backend effectue alors un calcul symétrique sur la chaîne correspondante pour vérifier l'identité de la passerelle. Si votre service backend se trouve dans un VPC et se connecte à la passerelle via un réseau privé, comme c'est le cas pour les API dans un environnement VPC dédié, une signature backend n'est pas requise car le canal est sécurisé.

La fonctionnalité de clé de signature d'origine est désormais intégrée au système de plug-ins. L'interface de console et les API existantes restent disponibles. La fonctionnalité de clé de signature d'origine et le plug-in de signature backend sont du même type et sont soumis aux mêmes restrictions d'attachement.

Les modifications apportées via l'API ou la console pour la fonctionnalité de clé de signature d'origine sont synchronisées avec le système de plug-ins. Toutefois, la synchronisation à distance n'est pas prise en charge.

2. Attachement du plug-in

Une fois une clé attachée à une API, la passerelle inclut des informations de signature dans toutes les requêtes envoyées au service backend pour cette API. Votre backend doit effectuer un calcul symétrique pour valider la signature et authentifier l'identité de la passerelle.

Pour remplacer la clé d'une API, modifiez directement la clé et le secret dans le plug-in. Les modifications prennent effet immédiatement pour toutes les API attachées.

3. Configuration du plug-in

Vous pouvez configurer le plug-in au format JSON ou YAML. Les deux formats utilisent le même schéma ; utilisez un convertisseur YAML vers JSON pour basculer de l'un à l'autre. Le bloc de code suivant présente un modèle au format YAML :

---
type: APIGW_BACKEND
key: SampleKey
secret: SampleSecret
isGenerateContentSha256Header: false   # (Optional) Specifies whether to add "x-ca-signed-payload" from the client request to the signature header. Default: false.                   

4. Lire la signature API Gateway

La signature calculée par la passerelle est stockée dans l'en-tête de requête X-Ca-Proxy-Signature.

5. Règles de signature backend

Pour obtenir une démonstration Java détaillée du calcul de signature, consultez l'exemple de code à l'adresse https://github.com/aliyun/api-gateway-demo-sign-backend-java.

La procédure de calcul de signature est la suivante :

1. API Gateway extrait des données spécifiques de la requête HTTP envoyée au backend et les combine dans une chaîne à signer. Le format de la chaîne à signer est le suivant :

   HTTPMethod
   Content-MD5
   Headers
   PathAndParameters

   Ces quatre champs constituent la chaîne à signer et sont séparés par des sauts de ligne (\n). Vous devez inclure le séparateur de saut de ligne même pour les champs vides, à une exception près : si le champ Headers est vide, n'ajoutez pas de saut de ligne après celui-ci. La signature est sensible à la casse. Les règles d'extraction de chaque champ sont décrites ci-dessous :

   • HTTPMethod : la méthode HTTP en majuscules, telle que POST.

   • Content-MD5 : la passerelle lit la valeur de l'en-tête Content-MD5 depuis la requête du client. Si le client n'envoie pas cet en-tête, la valeur Content-MD5 dans la chaîne à signer est vide. Le client ne doit calculer et envoyer l'en-tête Content-MD5 que lorsque la requête possède un corps qui n'est pas encodé sous forme de formulaire. Le code Java suivant montre comment calculer la valeur Content-MD5 :

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

   • Headers : ce champ contient toutes les clés et valeurs d'en-tête qui font partie du calcul de signature. Les clés des en-têtes à inclure dans la signature sont lues depuis l'en-tête de requête X-Ca-Proxy-Signature-Headers, où plusieurs clés sont séparées par des virgules. Pour construire cette partie de la chaîne, triez d'abord toutes les clés d'en-tête incluses dans le calcul de signature par ordre alphabétique. Ensuite, convertissez les clés d'en-tête en minuscules et concaténez les clés et les valeurs comme suit :

     String headers = HeaderKey1.toLowerCase() + ":" + HeaderValue1 +"\n"+
      HeaderKey2.toLowerCase() + ":" + HeaderValue2 +"\n"+
      ... +
     HeaderKeyN.toLowerCase() + ":" + HeaderValueN + "\n"

   • PathAndParameters

     Ce champ inclut le chemin et tous les paramètres de la requête et du formulaire. Pour construire cette chaîne, ajoutez un ? au chemin s'il existe des paramètres de requête ou de formulaire. Ensuite, triez les clés de tous les paramètres de requête et de formulaire par ordre alphabétique et concaténez-les comme indiqué ci-dessous. S'il n'y a aucun paramètre de requête ou de formulaire, PathAndParameters correspond simplement au chemin.

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

     Remarque

     Un paramètre de requête ou de formulaire peut avoir plusieurs valeurs. Si un paramètre a plusieurs valeurs, seule la première valeur est utilisée dans le calcul de signature. Si un paramètre est présent, le signe égal (=) doit être inclus dans la chaîne à signer, même si la valeur est vide. Par exemple, si la chaîne de requête est path?a=&b, elle doit être écrite path?a=&b= pour le calcul de signature.

2. Calculez la signature :

   Mac hmacSha256 = Mac.getInstance("HmacSHA256");
   byte[] keyBytes = secret.getBytes("UTF-8");  // secret is the signature key attached to the API
   hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
   String sign = new String(Base64.encodeBase64(hmacSha256.doFinal(stringToSign.getBytes("UTF-8"))),"UTF-8");

   La signature finale est générée en encodant la chaîne à signer (StringToSign) dans un tableau d'octets en UTF-8, en chiffrant le tableau d'octets résultant avec un algorithme de chiffrement, puis en encodant le résultat chiffré avec l'algorithme Base64.

6. Mode débogage

Pour simplifier l'intégration et les tests de la signature backend, activez le mode débogage en ajoutant l'en-tête X-Ca-Request-Mode: debug à votre requête vers API Gateway.

Votre service backend peut alors lire l'en-tête X-Ca-Proxy-Signature-String-To-Sign. Dans cet en-tête, les caractères de saut de ligne sont remplacés par # car les sauts de ligne ne sont pas autorisés dans les en-têtes HTTP.

7. Validation de l'horodatage

Si votre backend doit valider l'horodatage, sélectionnez le paramètre système CaRequestHandleTime dans la définition de l'API. Ce paramètre fournit l'heure UTC à laquelle la passerelle a reçu la requête.