Modifications apportées à Edge pour le cloud privé 4.53.01

Présentation des modifications

Edge for Private Cloud 4.53.01 a introduit plusieurs modifications qui améliorent la sécurité de la plate-forme en intégrant des versions mises à jour des logiciels et des bibliothèques. Ces modifications concernent :

  • Règle de validation OAS (spécification OpenAPI)
  • Règles compatibles avec les requêtes JSONPath
  • Règle d'appel Java qui s'appuie sur des bibliothèques obsolètes
  • OpenLDAP

Cette section décrit différents types de modifications introduites dans la version 4.53.01 qui peuvent perturber vos workflows pendant ou après la mise à niveau. Nous aborderons également les méthodes permettant d'identifier les zones problématiques potentielles, ainsi que les méthodologies de mitigation ou les solutions de contournement.

Règle de validation OAS (spécification OpenAPI)

Contexte

La règle de validation OAS valide les requêtes ou réponses entrantes par rapport aux règles définies dans la spécification OpenAPI 3.0 (JSON ou YAML). Edge for Private Cloud 4.53.01 apporte des améliorations à la règle OAS (spécification OpenAPI), en se concentrant sur une validation plus stricte et plus précise des corps de réponse de l'API.

Modifications

Edge for Private Cloud 4.53.01 introduit deux modifications importantes dans la façon dont la règle OAS valide les réponses de l'API, ce qui permet de mieux s'aligner sur votre spécification OpenAPI :

  • Scénario 1
    • Comportement précédent : si votre spécification OpenAPI exigeait un corps de réponse, mais que la réponse réelle de la cible ou de la règle en amont n'en incluait pas, la règle ne signalait pas cette erreur de validation.
    • Comportement actuel : dans ce scénario, la règle renvoie désormais correctement une erreur de validation (par exemple, defines a response schema but no response body found), indiquant une incohérence entre la réponse attendue et la réponse réelle.
  • Scénario 2 :
    • Comportement précédent : si votre spécification OpenAPI indiquait explicitement qu'aucun corps de réponse n'était attendu, mais que la réponse réelle de la règle cible ou en amont incluait un corps, la règle n'entraînait pas d'échec.
    • Comportement actuel : dans ce scénario, la règle entraînera désormais un échec (par exemple, No response body is expected but one was found), ce qui garantit que les réponses respectent strictement le schéma spécifié.

Atténuation

Identifiez les éventuels proxys ou flux partagés où la règle de validation OAS est configurée avec un tag Source défini sur response, ou ceux qui valident la réponse de toute autre règle générant une réponse.

Une fois qu'un proxy/flux partagé est identifié, assurez-vous que la réponse et la spécification OAS sont alignées. La réponse doit être strictement conforme à votre spécification OpenAPI concernant la présence ou l'absence d'un corps de réponse. Vous pouvez utiliser le traçage Apigee standard pour examiner vos modèles de trafic. Si la cible renvoie une réponse par intermittence, utilisez d'autres règles pour la valider avant la règle OAS.

  • Si votre fichier de spécification OAS définit un corps de réponse, la réponse de la stratégie cible ou en amont doit toujours en fournir un.
  • Si votre fichier de spécification OAS ne définit pas de corps de réponse, la règle cible ou en amont ne doit pas en envoyer.

Mettez à jour la règle de validation OAS ou votre comportement cible si nécessaire avant de tenter la mise à niveau vers Private Cloud 4.53.01. Vous devez d'abord valider ces workflows identifiés dans vos environnements hors production pour minimiser le risque d'interruption lors de la mise à niveau du cluster de production.

Chemin d'accès JSON

Contexte

Edge pour Private Cloud 4.53.01 a modifié la façon dont les expressions de chemin JSON sont utilisées dans différentes règles. Les expressions JSONPath peuvent être utilisées dans des règles telles que ExtractVariable, RegularExpressionProtection et Masquage des données pour analyser le contenu JSON ou stocker des valeurs dans des variables. Les expressions JSONPath peuvent également être utilisées dans la modélisation des messages en général pour remplacer les variables par des valeurs de manière dynamique lors de l'exécution du proxy. Les nouvelles expressions et les nouveaux formats JSONPath suivent les dernières normes d'expression JSON.

Modifications

Il est important d'examiner les flux partagés/proxys d'API existants pour identifier les règles qui utilisent des expressions JSONPath. Cela inclut, sans s'y limiter, la règle Extract Variables, la règle Regular Expression Protection ou toute règle avec un modèle de message utilisant JSONPath.

L'entrée JSON ci-dessous est utilisée pour expliquer les modifications :

{
  "store": {
    "book": [
      {"category": "reference", "author": "Nigel Rees", "price": 8.95},
      {"category": "fiction", "author": "Evelyn Waugh", "price": 12.99},
      {"category": "fiction", "author": "Herman Melville", "price": 8.99}
    ],
    "bicycle": {
      "color": "red",
      "book": [
        {"author": "Abc"}
      ]
    }
  }
}
  1. Modification du comportement du caractère générique JSONPath [*] pour les valeurs d'objet

    Le comportement du caractère générique [*] a été modifié lorsqu'il est utilisé pour accéder à toutes les valeurs immédiates d'un objet JSON. Auparavant, $.object[*] renvoyait les valeurs immédiates encapsulées dans un seul objet JSON. Avec les bibliothèques mises à jour, le résultat est désormais un tableau contenant ces valeurs.

    Par exemple, $.store[*] :

    Comportement précédent : 
    {
  "bicycle": {
    "color": "red",
    "book": [{"author": "Abc"}]
  },
  "book": [
    {"price": 8.95, "category": "reference", "author": "Nigel Rees"},
    {"price": 12.99, "category": "fiction", "author": "Evelyn Waugh"},
    {"price": 8.99, "category": "fiction", "author": "Herman Melville"}
  ]
}
    Comportement actuel : 
    [
  [
    {"category": "reference", "author": "Nigel Rees", "price": 8.95},
    {"category": "fiction", "author": "Evelyn Waugh", "price": 12.99},
    {"category": "fiction", "author": "Herman Melville", "price": 8.99}
  ],
  {
    "color": "red",
    "book": [{"author": "Abc"}]
  }
]
    Action :

    Modifiez l'expression JSONPath pour cibler simplement l'objet parent (par exemple, $.store) afin de cibler directement les éléments récupérés précédemment.

  2. Le point (.) à la fin des chemins JSONPath provoque une erreur

    La validation des expressions JSONPath est plus stricte. Auparavant, les chemins d'accès se terminant par un point non valide (par exemple, $.path.to.element.) étaient ignorés silencieusement, et la requête renvoyait toujours un résultat si le segment de chemin d'accès valide précédent correspondait. Avec la nouvelle version, ces chemins mal formés sont désormais correctement identifiés comme non valides et génèrent une erreur.

    Par exemple : $.store.book.

    Comportement précédent : 
    [
  {"price":8.95,"category":"reference","author":"Nigel Rees"},
  {"price":12.99,"category":"fiction","author":"Evelyn Waugh"},
  {"price":8.99,"category":"fiction","author":"Herman Melville"}
]
    Comportement actuel : 
    ERROR: com.jayway.jsonpath.InvalidPathException - Path must not end with a '.' or '..'

    Toutes les règles existantes qui utilisent des expressions JSONPath avec un point de fin involontaire échoueront désormais avec un InvalidPathException.

    Actions :

    Supprimez le point final de toute expression JSONPath qui se termine par un point. Par exemple, remplacez $.store.book. par $.store.book.

  3. Modification de la structure de sortie de la descente récursive JSONPath (..)

    La façon dont les résultats sont renvoyés a changé lorsque vous utilisez l'opérateur (..) (descente récursive) pour localiser toutes les occurrences d'un élément nommé. Auparavant, tous les éléments trouvés étaient aplatis dans une seule liste. Les bibliothèques mises à jour renvoient désormais une liste de listes, ce qui préserve la structure de regroupement d'origine dans laquelle les éléments ont été trouvés, au lieu d'une seule liste plate.

    Par exemple : $..book

    Comportement précédent : 
    [
  {"price":8.95,"category":"reference","author":"Nigel Rees"},
  {"price":12.99,"category":"fiction","author":"Evelyn Waugh"},
  {"price":8.99,"category":"fiction","author":"Herman Melville"},
  {"author":"Abc"}
]
    Comportement actuel : 
    [
  [
    {"category":"reference","author":"Nigel Rees","price":8.95},
    {"category":"fiction","author":"Evelyn Waugh","price":12.99},
    {"category":"fiction","author":"Herman Melville","price":8.99}
  ],
  [
    {"author":"Abc"}
  ]
]
    Action :

    Mettez à jour votre logique de traitement en aval pour tenir compte de la nouvelle structure de tableau imbriqué. Vous devrez probablement parcourir le JSONArray externe, puis chaque JSONArray interne pour accéder aux éléments individuels.

  4. L'indexation JSONPath après une sélection ou un filtre multi-éléments renvoie un tableau vide

    Le comportement change lorsqu'un index (par exemple, [0]) est appliqué immédiatement après un sélecteur à plusieurs éléments (comme [*]) ou un filtre ([?(condition)]). Auparavant, ces expressions tentaient de sélectionner l'élément à l'index spécifié à partir des résultats combinés. Avec la nouvelle version, ces expressions renverront désormais un tableau vide ([]).

    Par exemple : $.store.book[*][0]

    Comportement précédent : 
    {"category": "reference", "price": 8.95, "author": "Nigel Rees"}
    Comportement actuel : 
    []
    Action :

    Si vous devez filtrer un ensemble de données, puis obtenir un élément spécifique de l'ensemble filtré, traitez le tableau filtré renvoyé par JSONPath (par exemple, $..book[?(@.category == 'fiction')]), puis prenez [0] à partir du résultat précédent.

  5. Modification de la sortie du découpage de tableau négatif JSONPath

    La nouvelle version a modifié le comportement du découpage de tableau négatif (exemple : [-2:], [-1:]). Auparavant, lorsqu'un découpage négatif était appliqué à un tableau (indiquant les éléments à partir de la fin du tableau), l'ancienne version renvoyait à tort un seul élément de ce découpage. La nouvelle version renvoie désormais correctement une liste (tableau) contenant tous les éléments qui se trouvent dans la plage négative spécifiée.

    $.store.book[-2:] par exemple.

    Comportement précédent : 
    {"price":12.99,"category":"fiction","author":"Evelyn Waugh"}
    Comportement actuel : 
    [
  {"category":"fiction","author":"Evelyn Waugh","price":12.99},
  {"category":"fiction","author":"Herman Melville","price":8.99}
]
    Action :

    La logique de traitement en aval doit maintenant être mise à jour pour parcourir le tableau JSON renvoyé afin d'obtenir le résultat souhaité.

  6. Point précédent plus strict dans JSONPath

    L'application de la syntaxe est plus stricte pour les éléments auxquels vous accédez directement depuis la racine. Lorsque les éléments sont accessibles directement à partir de la racine sans point précédent (exemple : $propertyelement), cette syntaxe est désormais considérée comme une erreur et empêche le déploiement du proxy.

    Par exemple, $store.

    {
  "bicycle": {
    "color": "red",
    "book": [{"author": "Abc"}]
  },
  "book": [
    {"price": 8.95, "category": "reference", "author": "Nigel Rees"},
    {"price": 12.99, "category": "fiction", "author": "Evelyn Waugh"},
    {"price": 8.99, "category": "fiction", "author": "Herman Melville"}
  ]
}

    Comportement actuel :

    Proxy will fail to deploy.

    Actions :

    Modifiez votre JSONPath pour inclure le point : $.propertyName (par exemple, $.store). Cela permettra de cibler et de récupérer correctement la valeur.

  7. Expressions JSONPath dynamiques

    Portez une attention particulière aux règles dans lesquelles l'expression JSONPath elle-même est fournie par une variable (par exemple, {myJsonPathVariable} ou {dynamicPath}). La valeur de ces variables doit également être vérifiée par rapport aux changements de comportement potentiels décrits ci-dessus.

Atténuation

Pour l'atténuer, une stratégie globale est nécessaire. Ce processus consiste à choisir le chemin de mise à jour approprié et à appliquer le correctif nécessaire pour les expressions JSONPath cassées.

Choisissez la méthode de mise à niveau qui vous convient le mieux :

  • Migration sans temps d'arrêt

    Cette stratégie consiste à acquérir un ou plusieurs nouveaux environnements afin de pouvoir y connecter des nœuds de processeur de messages distincts. Ces nœuds de processeur de messages peuvent être configurés pour installer la version 4.53.01 et disposer de proxys avec des expressions JSONPath modernes. Elles peuvent être utilisées pendant la mise à niveau et être mises hors service une fois la mise à niveau terminée. Cette stratégie est transparente, mais implique de se procurer temporairement des nœuds de processeur de messages supplémentaires pour assurer une mise à niveau fluide. Voici les détails :

    • Créez un nouvel environnement et ajoutez-y de nouveaux nœuds de processeur de messages de la version 4.53.01.
    • Importez le groupe de proxys concernés dans le nouvel environnement, appliquez les corrections nécessaires expliquées dans la section sur la correction, puis déployez le groupe de proxys mis à jour dans le nouvel environnement.
    • Redirigez le trafic vers le nouvel environnement et annulez le déploiement des proxys concernés dans l'ancien environnement.
    • Mettez à niveau les nœuds du processeur de messages d'origine vers la version 4.53.01. Déployez les proxys qui contiennent des correctifs pour JSONPath dans l'environnement d'origine.
    • Redirigez le trafic vers l'ancien environnement, qui dispose désormais de processeurs de messages sur la version 4.53.01 et d'un proxy modernisé pour les nouvelles expressions JSONPath.
    • Supprimez et mettez hors service le nouvel environnement et les nœuds associés.
  • Temps d'arrêt et mise à niveau

    Cette stratégie consiste à prévoir un temps d'arrêt pour les proxys d'API utilisant des expressions de chemin JSON incorrectes. Cela ne nécessite pas l'acquisition de nœuds de processeur de messages supplémentaires, mais perturbe le trafic d'API pour les proxys concernés.

    • Identifiez les proxys concernés par les stratégies affectées et générez une nouvelle révision pour tous les proxys concernés.
    • Appliquez les corrections nécessaires en implémentant les corrections expliquées dans la section sur la correction dans une nouvelle révision du proxy. Ne déployez pas encore cette application.
    • Prévoyez un temps d'arrêt pour le ou les proxys concernés.
    • Mettez à niveau tous les processeurs de messages vers Edge pour le cloud privé version 4.53.01. Notez que les proxys existants peuvent échouer sur les processeurs de messages nouvellement mis à niveau.
    • Une fois tous les processeurs de messages mis à niveau vers Edge pour le cloud privé version 4.53.01 , déployez la révision de proxy nouvellement créée avec l'expression JSONPath corrigée.
    • Rétablissez le trafic sur ces proxys.
  • Redesign Proxy avant la mise à niveau

    Vous pouvez reconcevoir le proxy lui-même avant de passer à Edge pour le cloud privé 4.53.01. Au lieu de vous appuyer sur des expressions de chemin JSON spécifiques, vous pouvez obtenir le même résultat en utilisant une autre méthode.

    Par exemple, si vous utilisez une règle Extract Variables avec un chemin JSON, vous pouvez remplacer la règle par une règle JavaScript qui extrait des données similaires avant de passer à la version la plus récente. Une fois la mise à niveau terminée, vous pouvez à nouveau utiliser des chemins JSON avec des formats plus récents pour votre proxy.

Modifications de JavaCallout

Contexte

Les versions 4.53.00 et antérieures d'Edge pour le cloud privé contenaient un répertoire appelé deprecated ($APIGEE_ROOT/edge-message-processor/lib/deprecated) qui contenait un ensemble de bibliothèques JAR. Ces bibliothèques étaient disponibles pour être utilisées dans le code Java de la règle JavaCallout et pouvaient être utilisées par votre code Java personnalisé directement ou indirectement.

Modifications

Le répertoire deprecated a été supprimé dans la version 4.53.01 d'Edge pour le cloud privé. Si votre code Java repose sur de telles bibliothèques, les proxys utilisant de tels appels Java échoueront lorsque les processeurs de messages seront mis à niveau vers la version 4.53.01. Pour éviter de tels échecs, suivez les étapes d'atténuation ci-dessous avant de mettre à niveau les processeurs de messages vers la version 4.53.01.

Atténuation

  1. Examinez vos règles Java-Callout et les fichiers JAR associés, et identifiez ceux qui référencent ou utilisent des bibliothèques présentes dans le répertoire "deprecated" (obsolète) de vos processeurs de messages actuels. Notez que les appels Java peuvent utiliser des fichiers JAR importés en tant que ressources au niveau de l'organisation ou de l'environnement. Pensez également à ces bibliothèques.
  2. Une fois que vous avez identifié ces bibliothèques obsolètes , vous pouvez suivre l'une des méthodes ci-dessous pour résoudre le problème.
    • Placement des ressources (recommandé si vous avez un petit nombre de fichiers JAR / bibliothèques provenant du répertoire obsolète qui sont référencés par les fichiers JAR Java-Callout)
      • Importez les fichiers JAR obsolètes identifiés en tant que ressource au niveau souhaité : révision du proxy d'API, environnement ou organisation.
      • Procédez à la mise à niveau du logiciel Apigee comme d'habitude.
    • Placement manuel (recommandé si vous avez un grand nombre de fichiers JAR / bibliothèques référencés par les fichiers JAR Java-Callout)
      • Sur chaque nœud de processeur de messages, créez un répertoire nommé external-lib dans le chemin d'accès $APIGEE_ROOT/data/edge-message-processor/.
      • Copiez les fichiers JAR identifiés dans le répertoire external-lib à partir du répertoire obsolète : cp $APIGEE_ROOT/edge-message-processor/lib/deprecated/some.jar $APIGEE_ROOT/data/edge-message-processor/external-lib/some.jar
      • Assurez-vous que le répertoire et les fichiers JAR sous-jacents sont lisibles par l'utilisateur Apigee : chown -R apigee:apigee $APIGEE_ROOT/data/edge-message-processor/external-lib
      • Procédez à la mise à niveau du logiciel Apigee comme d'habitude.

Modification d'OpenLDAP

Contexte

OpenLDAP peut être utilisé dans Edge Private Cloud pour l'authentification et l'autorisation. Dans Edge pour le cloud privé 4.53.01, le logiciel OpenLDAP fourni par Apigee est passé de la version 2.4 à la version 2.6.

Modifications

Dans OpenLDAP 2.6, le nom distinctif relatif (RDN) est limité à environ 241 octets/caractères. Il s'agit d'une limite stricte qui ne peut pas être modifiée.

Impact
  • Des échecs de réplication ou d'importation se produisent pour les entrées dont les RDN sont trop volumineux.
  • Toute tentative de création d'entités telles que des organisations, des environnements, des rôles personnalisés, des autorisations, etc. peut générer le message d'erreur "message": "[LDAP: error code 80 - Other]".
  • Tout nom distinctif de plus de 241 octets dans le LDAP d'Apigee est concerné. Ces DN empêcheront la mise à niveau du logiciel Apigee OpenLDAP. Vous devrez suivre des stratégies d'atténuation pour ces éléments avant de pouvoir procéder à la mise à niveau.

En général, dans le LDAP d'Apigee, les DN longs sont liés aux autorisations, car ils sont créés en concaténant plusieurs entités. Ces entrées d'autorisation sont particulièrement sujettes aux problèmes de mise à niveau.

Par exemple, 

dn: cn=@@@environments@@@*@@@applications@@@*@@@revisions@@@*@@@debugsessions,ou=resources,cn=businessuser,ou=userroles,o=orgname,ou=organizations,dc=apigee,dc=com

En règle générale, les noms d'organisation, d'environnement et de rôle sont de longueur telle que les RDN dans LDAP finissent par être inférieurs à 241 octets.

Atténuation

Avant la mise à niveau vers la version 4.53.01 :

Les étapes suivantes vous aideront à vérifier la présence de longs RDN dans votre cluster LDAP 2.4 existant.

Étape 1 : Extraire les données LDAP

Utilisez la commande ldapsearch pour trouver le nom distinctif (dn) et redirigez la sortie vers un fichier : 

ldapsearch -o ldif-wrap=no -b "dc=apigee,dc=com" -D "cn=manager,dc=apigee,dc=com" -H ldap://:10389 -LLL -x -w LDAP_PASSWORD dn > /tmp/DN.ldif

Assurez-vous que le fichier DN.ldif ci-dessus contient des entrées LDAP.

#2 – Identifier les longs noms de domaine enregistrés

Recherchez les RDN dépassant 241 octets/caractères dans le fichier DN.ldif ci-dessus :

cat /tmp/DN.ldif |  grep '^dn:' | gawk -F',|dn: ' '{ rdn = $2; char_count = length(rdn); cmd = "echo -n \"" rdn "\" | wc -c"; cmd | getline byte_count; close(cmd); if (char_count > 241 || byte_count > 241) { print rdn, "(chars: " char_count ") (bytes: " byte_count ")"; }}'
o=VeryLongOrgNameWithMoreThan241Chars.... (chars: 245) (bytes: 245)
cn=VeryLongCustomRoleNameWithMoreThan241Chars.... (chars: 258) (bytes: 258)

Si la commande ci-dessus ne produit aucun résultat, cela signifie qu'aucun nom distinctif relatif (RDN) de la configuration LDAP existante ne dépasse 241 octets/caractères. Vous pouvez procéder à la mise à niveau comme d'habitude.

Si la commande ci-dessus génère un résultat, cela indique la présence de noms distinctifs relatifs (RDN) de plus de 241 octets/caractères. Pour ces éléments, suivez les étapes d'atténuation décrites à l'étape 3 avant de procéder à la mise à niveau vers Edge pour le cloud privé 4.53.01.

#3 : Gérer les longs RDN

Si vous recevez un résultat à l'étape 2, cela indique la présence de noms distinctifs relatifs (RDN) dépassant 241 octets/caractères. Suivez les étapes d'atténuation ci-dessous :

Examinez les entrées LDAP qui dépassent 241 octets.

  • Si le nom de rôle personnalisé, d'application, de produit d'API ou d'autres entités est la principale cause de la longueur du nom distinctif relatif, migrez vers une autre entité avec un nom plus court.
  • Si le nom de l'organisation ou de l'environnement est la principale cause de la longueur du RDN, vous devrez migrer vers une autre organisation ou un autre environnement dont le nom est plus court.

Répétez les étapes ci-dessus jusqu'à ce que votre LDAP ne contienne plus de RDN de plus de 241 octets. Une fois que vous avez atteint cet état, procédez à la mise à niveau de la version du cloud privé comme d'habitude.

Modifications apportées au fournisseur de cryptographie

Contexte

Cette modification est une reprise d'Edge pour le cloud privé 4.53.00. Dans Edge for Private Cloud 4.53.00, le fournisseur de chiffrement interne est passé de Bouncy Castle (BC) à Bouncy Castle FIPS (BCFIPS) pour activer la compatibilité FIPS.

Modifications

Si les règles JavaCallout s'appuient sur l'utilisation du fournisseur BC d'origine, en particulier lors de l'utilisation de fonctionnalités de sécurité renforcées dans le fournisseur BCFIPS (par exemple, l'utilisation d'une paire de clés commune pour le chiffrement et la signature), ces règles JavaCallout devront être modernisées. Les règles JavaCallout qui tentent de charger le fournisseur de chiffrement Bouncy Castle à l'aide du nom BC peuvent échouer, car le fournisseur par défaut a changé. Ces règles utilisant le fournisseur BC peuvent ensuite être interrompues. Toutes les implémentations personnalisées reposant sur l'ancien fournisseur BC ne seront plus accessibles. Elles devront être examinées et réimplémentées.

Atténuation

La solution de contournement recommandée consiste à utiliser le fournisseur BCFIPS. Les implémentations JavaCallout personnalisées qui s'appuyaient sur l'ancien fournisseur devront être examinées et réimplémentées à l'aide du fournisseur Bouncy Castle FIPS, accessible à l'aide de la chaîne "BCFIPS".

Outil de détection automatique des modifications

Un outil de détection des modifications devrait bientôt être disponible. Cet outil pourra analyser et identifier les proxys d'API, les flux partagés, les ressources et les RDN LDAP potentiellement concernés par les différentes modifications décrites dans cet article. Cet outil devrait vous aider à identifier les différentes entités susceptibles d'échouer lors de la mise à niveau vers Edge pour le cloud privé 4.53.01 ou après.