Изменения в Edge для частного облака 4.53.01

Обзор изменений

В Edge for Private Cloud версии 4.53.01 представлено множество изменений, повышающих безопасность платформы, включая обновлённые версии программного обеспечения и библиотек. Эти изменения затрагивают:

  • Политика проверки OAS (спецификация OpenAPI)
  • Политики, поддерживающие запросы JSONPath
  • Политика вызовов Java, которая использует устаревшие библиотеки
  • OpenLDAP

В этом разделе описываются различные типы изменений, внесённых в версию 4.53.01, которые могут нарушить ваши рабочие процессы во время или после обновления. Также рассматриваются методы выявления потенциальных проблемных областей и способы их устранения или обхода.

Политика проверки OAS (спецификация OpenAPI)

Контекст

Политика валидации OAS проверяет входящие запросы и ответы на соответствие правилам, определённым в спецификации OpenAPI 3.0 (JSON или YAML). Edge for Private Cloud 4.53.01 предлагает усовершенствования политики OAS (спецификация OpenAPI), направленные на более строгую и точную валидацию тел ответов API.

Изменения

Edge for Private Cloud 4.53.01 вносит два важных изменения в способ проверки ответов API политикой OAS, обеспечивая более тесное соответствие вашей спецификации OpenAPI:

  • Сценарий 1:
    • Предыдущее поведение: если спецификация OpenAPI требовала тела ответа, но фактический ответ от целевой или вышестоящей политики не включал его, политика не отмечала это как ошибку проверки.
    • Текущее поведение: политика теперь будет правильно возвращать ошибку проверки (пример: defines a response schema but no response body found ) в этом сценарии, указывая на несоответствие между ожидаемым и фактическим ответом.
  • Сценарий 2:
    • Предыдущее поведение: если в вашей спецификации OpenAPI явно указано, что тело ответа не ожидается, но фактический ответ от целевой или вышестоящей политики включал тело, политика не привела бы к сбою.
    • Текущее поведение: Теперь политика приведет к сбою (пример: No response body is expected but one was found ) в этом сценарии, гарантируя, что ответы строго соответствуют указанной схеме.

Смягчение

Определите все прокси-серверы или общие потоки, в которых политика проверки OAS настроена с тегом Source , установленным на response , или те, которые проверяют ответ из любой другой политики, которая генерирует ответ.

После определения прокси-сервера/совместного потока убедитесь в соответствии ответа спецификации OAS. Ответ должен строго соответствовать спецификации OpenAPI в отношении наличия или отсутствия тела ответа. Вы можете использовать стандартную трассировку Apigee для анализа шаблонов трафика. Если целевой объект возвращает ответ с перерывами, используйте другие политики для его проверки перед применением политики OAS.

  • Если ваш файл спецификации OAS определяет тело ответа, ответ от целевой или вышестоящей политики всегда должен его предоставлять.
  • Если ваш файл спецификации OAS не определяет тело ответа, целевая или вышестоящая политика не должна его отправлять.

При необходимости обновите политику проверки OAS или целевое поведение перед попыткой обновления до Private Cloud 4.53.01. Необходимо сначала проверить выявленные рабочие процессы в непроизводственных средах, чтобы минимизировать риск сбоев при обновлении производственного кластера.

JSON-путь

Контекст

В Edge for Private Cloud версии 4.53.01 внесены изменения в порядок использования выражений путей JSON в различных политиках. Выражения JSONPath можно использовать в таких политиках, как ExtractVariable , RegularExpressionProtection и Data Masking , для анализа содержимого JSON или сохранения значений в переменных. Выражения JSONPath также можно использовать в шаблонах общих сообщений для динамической замены переменных значениями во время выполнения прокси-сервера. Новые выражения и форматы JSONPath соответствуют последним стандартам выражений JSON.

Изменения

Важно проверить существующие прокси-серверы API/общие потоки на наличие политик, использующих выражения JSONPath. Это включает, помимо прочего, политику извлечения переменных, политику защиты регулярных выражений и любую политику с шаблоном сообщения, использующим JSONPath.

Ниже приведен JSON-вход, используемый для объяснения изменений:

{
  "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. Изменение поведения подстановочного знака JSONPath [*] для значений объектов

    Изменено поведение подстановочного знака [*] при использовании для доступа ко всем непосредственным значениям JSON-объекта. Ранее $.object[*] возвращал непосредственные значения, обёрнутые в один JSON-объект. С обновлёнными библиотеками вывод теперь представляет собой массив, содержащий эти значения.

    Например, $.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"}
  ]
}
    Текущее поведение:
    [
  [
    {"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"}]
  }
]
    Действие:

    Измените выражение JSONPath так, чтобы оно просто указывало на родительский объект (например: $.store ), чтобы напрямую указать элементы, которые были извлечены ранее.

  2. JSONPath: завершающая точка (.) в путях приводит к ошибке

    Валидация выражений JSONPath стала более строгой. Ранее пути, заканчивающиеся недопустимой точкой (например, $.path.to.element. ), игнорировались без уведомления, и запрос всё равно возвращал результат, если предыдущий допустимый сегмент пути совпадал. В новой версии такие некорректные пути теперь корректно определяются как недопустимые и приводят к ошибке.

    Например, $.store.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"}
]
    Текущее поведение:
    ERROR: com.jayway.jsonpath.InvalidPathException - Path must not end with a '.' or '..'

    Любые существующие политики, использующие выражения JSONPath с непреднамеренной конечной точкой, теперь будут завершаться ошибкой с исключением InvalidPathException .

    Действие:

    Удалите точку в конце любого выражения JSONPath, заканчивающегося на единицу. Например, измените $.store.book. на $.store.book .

  3. Изменение структуры выходных данных рекурсивного спуска JSONPath (..)

    Изменён порядок возврата результатов при использовании оператора (..) (рекурсивного спуска) для поиска всех вхождений именованного элемента. Ранее все найденные элементы сводились в один список. Обновлённые библиотеки теперь возвращают список списков, сохраняя исходную структуру группировки, в которой были найдены элементы, а не один плоский список.

    Например, $..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"},
  {"author":"Abc"}
]
    Текущее поведение:
    [
  [
    {"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"}
  ]
]
    Действие:

    Обновите логику обработки данных ниже по цепочке, чтобы учесть новую структуру вложенного массива. Скорее всего, вам потребуется сначала пройтись по внешнему массиву JSONArray, а затем по каждому внутреннему массиву JSONArray, чтобы получить доступ к отдельным элементам.

  4. Индексация JSONPath после выбора нескольких элементов или фильтрации возвращает пустой массив

    Изменено поведение функции, когда индекс (например, [0] ) применяется сразу после селектора нескольких элементов (например, [*] ) или фильтра ( [?(condition)] ). Ранее такие выражения пытались выбрать элемент с указанным индексом из объединённых результатов. В новой версии эти выражения теперь возвращают пустой массив ( [] ).

    Например, $.store.book[*][0]

    Предыдущее поведение:
    {"category": "reference", "price": 8.95, "author": "Nigel Rees"}
    Текущее поведение:
    []
    Действие:

    Если необходимо отфильтровать и затем получить определенный элемент из отфильтрованного набора, обработайте отфильтрованный массив, возвращаемый JSONPath, например, $..book[?(@.category == 'fiction')] , а затем возьмите [0] из предыдущего результата.

  5. Изменение выходных данных отрицательного среза массива JSONPath

    В новой версии изменено поведение отрицательного среза массива (пример: [-2:], [-1:] ). Ранее при применении отрицательного среза к массиву (указывающего на элементы с конца массива) старая версия ошибочно возвращала только один элемент из этого среза. Новая версия теперь корректно возвращает список (массив), содержащий все элементы, попадающие в указанный отрицательный диапазон.

    Например, $.store.book[-2:]

    Предыдущее поведение:
    {"price":12.99,"category":"fiction","author":"Evelyn Waugh"}
    Текущее поведение:
    [
  {"category":"fiction","author":"Evelyn Waugh","price":12.99},
  {"category":"fiction","author":"Herman Melville","price":8.99}
]
    Действие:

    Теперь необходимо обновить логику последующей обработки, чтобы она могла пройти по возвращенному массиву JSON и получить желаемый результат.

  6. JSONPath более строгая предварительная точка

    Синтаксис для элементов, доступ к которым осуществляется напрямую из корня, ужесточен. Если доступ к элементам осуществляется напрямую из корня без предшествующей точки (например, $propertyelement ), такой синтаксис теперь считается ошибкой и не позволит развернуть прокси.

    Например, $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"}
  ]
}

    Текущее поведение:

    Proxy will fail to deploy.

    Действие:

    Измените JSONPath, включив точку: $.propertyName (например, $.store ). Это позволит правильно указать и получить значение.

  7. Динамические выражения JSONPath

    Обратите особое внимание на политики, в которых выражение JSONPath само по себе предоставляется переменной (пример: {myJsonPathVariable} или {dynamicPath} ). Значение этих переменных также необходимо проверить на предмет возможных изменений в поведении, описанных выше.

Смягчение

Для устранения этой проблемы необходима комплексная стратегия. Этот процесс включает в себя выбор подходящего пути обновления и применение необходимых исправлений для устранения ошибок в выражениях JSONPath.

Выберите наиболее подходящий для вас метод обновления:

  • Миграция с нулевым временем простоя

    Эта стратегия предполагает приобретение одной или нескольких новых сред, к которым можно подключить отдельные узлы обработки сообщений. Такие узлы обработки сообщений можно настроить на установку версии 4.53.01 и использовать прокси-серверы с современными выражениями JSONPath. Их можно использовать во время обновления и вывести из эксплуатации после его завершения. Эта стратегия является беспроблемной, но требует временного приобретения дополнительных узлов обработки сообщений для обеспечения плавного обновления. Подробности ниже:

    • Создайте новую среду и добавьте в нее новые узлы обработки сообщений версии 4.53.01.
    • Загрузите пакет прокси для затронутых прокси-серверов в новую среду и примените необходимые исправления, описанные в разделе по исправлению, а затем разверните обновленный пакет прокси-сервера в новой среде.
    • Перенаправьте трафик в новую среду и отмените развертывание затронутых прокси-серверов из старой среды.
    • Обновите исходные узлы обработки сообщений до версии 4.53.01. Разверните прокси-серверы с исправлениями для JSONPath в исходной среде.
    • Переключите трафик обратно в старую среду, в которой теперь используются обработчики сообщений версии 4.53.01 и прокси-сервер, модернизированный для новых выражений jsonpath.
    • Удалить и вывести из эксплуатации новую среду и связанные с ней узлы.
  • Простой и обновление

    Эта стратегия предполагает обеспечение простоя API-прокси с использованием некорректных выражений JSON Path. Это не требует привлечения дополнительных узлов обработки сообщений, но приводит к сбоям в работе API-трафика затронутых прокси.

    • Определите затронутые прокси-серверы с затронутыми политиками и создайте новую версию для всех затронутых прокси-серверов.
    • Примените необходимые исправления, внедрив исправления, описанные в разделе «Исправление», в новую версию прокси-сервера. Пока не внедряйте это.
    • Обеспечить простои прокси-сервера/прокси-серверов с учетом воздействия.
    • Обновите все обработчики сообщений до версии Edge для частного облака 4.53.01. Обратите внимание, что существующие прокси-серверы могут работать со сбоями на обновлённых обработчиках сообщений.
    • После обновления всех обработчиков сообщений до версии Edge для частного облака 4.53.01 разверните вновь созданную версию прокси-сервера с исправленным выражением JSONPath.
    • Возобновите трафик на таких прокси.
  • Перепроектируйте прокси перед обновлением

    Вы можете перепроектировать сам прокси-сервер перед обновлением до Edge for Private Cloud 4.53.01. Вместо того, чтобы полагаться на конкретные выражения пути JSON, вы можете получить тот же результат, используя другой метод.

    Например, если вы используете политику извлечения переменных с JSON-путем, вы можете заменить её политикой Javascript, которая извлекает аналогичные данные перед обновлением до новой версии. После завершения обновления вы сможете вернуться к использованию JSON-путей с новыми форматами.

Изменения JavaCallout

Контекст

В Edge для частного облака версии 4.53.00 и более ранних версиях существовал каталог deprecated ( $APIGEE_ROOT/edge-message-processor/lib/deprecated ), содержащий ряд JAR-библиотек. Эти библиотеки были доступны для использования в коде Java в политике JavaCallout и могли использоваться вашим пользовательским кодом Java напрямую или косвенно.

Изменения

Устаревший каталог теперь удалён в Edge для частного облака версии 4.53.01. Если ваш Java-код использует такие библиотеки, прокси-серверы, использующие такие вызовы Java, будут работать со сбоями при обновлении обработчиков сообщений до версии 4.53.01. Чтобы избежать подобных сбоев, выполните следующие действия перед обновлением обработчиков сообщений до версии 4.53.01.

Смягчение

  1. Проверьте политики Java-Callout и связанные с ними JAR-файлы и определите, ссылаются ли они на библиотеки из каталога «deprecated» ваших текущих обработчиков сообщений или используют их. Обратите внимание, что Java-вызовы могут использовать JAR-файлы, загруженные как ресурсы уровня организации или среды. Обратите внимание и на эти библиотеки.
  2. После того как вы определили такие устаревшие библиотеки, вы можете воспользоваться одним из приведенных ниже методов решения проблемы.
    • Размещение ресурсов (рекомендуется, если у вас есть небольшое количество jar-файлов/библиотек из устаревшего каталога, на которые ссылаются jar-файлы Java-Callout)
      • Загрузите выявленные устаревшие jar-файлы в качестве ресурса на желаемом уровне: ревизия прокси API, среда или организация.
      • Продолжайте обновление программного обеспечения Apigee как обычно.
    • Ручное размещение (рекомендуется, если у вас большое количество jar-файлов/библиотек, на которые ссылаются jar-файлы Java-Callout)
      • На каждом узле процессора сообщений создайте новый каталог с именем external-lib по пути $APIGEE_ROOT/data/edge-message-processor/ .
      • Скопируйте идентифицированные JAR-файлы в этот каталог external-lib из устаревшего каталога: cp $APIGEE_ROOT/edge-message-processor/lib/deprecated/some.jar $APIGEE_ROOT/data/edge-message-processor/external-lib/some.jar
      • Убедитесь, что каталог и базовые jar-файлы доступны для чтения пользователю Apigee: chown -R apigee:apigee $APIGEE_ROOT/data/edge-message-processor/external-lib
      • Продолжайте обновление программного обеспечения Apigee как обычно.

Изменение OpenLDAP

Контекст

OpenLDAP можно использовать в Edge Private Cloud как для аутентификации, так и для авторизации. В Edge for Private Cloud 4.53.01 программное обеспечение OpenLDAP, поставляемое Apigee, было обновлено с версии 2.4 до 2.6.

Изменения

В OpenLDAP 2.6 длина относительного отличительного имени (RDN) ограничена примерно 241 байтом/символом. Это ограничение является жёстким и не может быть изменено.

Влияние
  • Для записей с чрезмерно большими RDN возникают сбои репликации или импорта.
  • Попытка создать такие сущности, как организации, среды, пользовательские роли, разрешения и т. д., может привести к появлению сообщения об ошибке: "message": "[LDAP: error code 80 - Other]" .
  • Любое DN длиной более 241 байта в LDAP Apigee подвержено уязвимости. Такие DN препятствуют успешному обновлению программного обеспечения Apigee OpenLDAP, и вам потребуется следовать стратегиям снижения рисков, прежде чем продолжить обновление.

Как правило, в LDAP Apigee длинные имена доменов связаны с разрешениями, поскольку они создаются путём объединения нескольких сущностей. Такие записи разрешений особенно подвержены проблемам при обновлении.

Например, 

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

Как правило, названия организаций, сред и ролей имеют такую ​​длину, что RDN в LDAP оказываются меньше 241 байта.

Смягчение

Перед обновлением до 4.53.01:

Следующие шаги помогут проверить наличие длинных RDN в вашем существующем кластере LDAP 2.4.

#1 — Извлечение данных LDAP

Используйте команду ldapsearch для поиска отличительного имени (dn) и перенаправления вывода в файл: 

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

Убедитесь, что файл DN.ldif выше содержит записи LDAP.

#2 — Определите длинные RDN

Найдите RDN, превышающие 241 байт/символ, в файле DN.ldif выше: 

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)

Если при выполнении указанной выше команды ничего не выводится, значит, ни одно из RDN-имен в текущей настройке LDAP не превышает 241 байт/символ. Вы можете продолжить обновление в обычном режиме.

Если при выполнении указанной выше команды есть результат, это указывает на наличие RDN, превышающих 241 байт/символ. Для таких элементов выполните действия по устранению уязвимости, описанные в шаге 3 , прежде чем приступать к обновлению Edge for Private Cloud до версии 4.53.01.

#3 — Обработка длинных RDN

Если на шаге 2 получены выходные данные, это указывает на наличие RDN, превышающих 241 байт/символ, и выполните следующие шаги по устранению проблемы:

Проверьте записи LDAP, размер которых превышает 241 байт.

  • Если основной причиной длинного RDN является имя пользовательской роли, приложения, продукта API или других сущностей, перейдите на использование альтернативной сущности с более коротким именем.
  • Если основным источником длинного RDN является название организации или среды, вам придется перейти на другую организацию или среду с более коротким именем.

Продолжайте повторять описанные выше шаги, пока в вашем LDAP не останется ни одного RDN-имени длиннее 241 байта. После достижения этого состояния продолжайте обновление версии частного облака как обычно.

Изменения поставщика криптографии

Контекст

Это изменение перенесено из Edge for Private Cloud 4.53.00. В Edge for Private Cloud 4.53.00 внутренний поставщик криптографии был обновлён с Bouncy Castle (BC) до Bouncy Castle FIPS (BCFIPS) для поддержки FIPS.

Изменения

Если политики JavaCallout используют исходного поставщика BC, особенно при использовании функций безопасности, усиленных в поставщике BCFIPS (например, использование общей пары ключей для шифрования и подписи), такие политики JavaCallout необходимо модернизировать. Политики JavaCallout, пытающиеся загрузить поставщик криптографии Bouncy Castle с именем BC, могут завершиться неудачей из-за смены поставщика по умолчанию. Такие политики, использующие поставщика BC, впоследствии могут перестать работать. Любые пользовательские реализации, использующие старого поставщика BC, больше не будут доступны и должны быть пересмотрены и реализованы заново.

Смягчение

Рекомендуемым решением является использование поставщика BCFIPS. Пользовательские реализации JavaCallout, основанные на старом поставщике, необходимо пересмотреть и переписать с использованием поставщика Bouncy Castle FIPS, доступ к которому можно получить с помощью строки «BCFIPS».

Автоматизированный инструмент обнаружения изменений

В ближайшее время планируется выпуск инструмента обнаружения изменений. Этот инструмент сможет сканировать и идентифицировать прокси-серверы API, общие потоки, ресурсы и RDN LDAP, которые потенциально могут быть затронуты различными изменениями, описанными в этой статье. Этот инструмент должен помочь выявить различные сущности, подверженные сбоям во время или после обновления до Edge for Private Cloud 4.53.01.