Mudanças no Edge para nuvem privada 4.53.01

Visão geral das mudanças

O Edge para nuvem privada 4.53.01 introduziu várias mudanças que melhoram a postura de segurança da plataforma, incorporando versões atualizadas de software/bibliotecas. Essas mudanças afetam:

  • Política de validação da especificação OpenAPI (OAS)
  • Políticas compatíveis com consultas JSONPath
  • Política de destaque de Java que depende de bibliotecas descontinuadas
  • OpenLDAP

Esta seção descreve vários tipos de mudanças introduzidas na versão 4.53.01 que podem interromper seus fluxos de trabalho durante ou após o upgrade. Também abordamos métodos para identificar possíveis áreas problemáticas e metodologias de mitigação ou soluções alternativas.

Política de validação da especificação OpenAPI (OAS)

Contexto

A política de validação do OAS valida solicitações ou respostas recebidas de acordo com as regras definidas na especificação OpenAPI 3.0 (JSON ou YAML). O Edge para nuvem privada 4.53.01 oferece melhorias na política OAS (especificação OpenAPI), com foco em uma validação mais rigorosa e precisa dos corpos de resposta da API.

Mudanças

O Edge para nuvem privada 4.53.01 introduz duas mudanças importantes na forma como a política OAS valida respostas da API, garantindo um alinhamento mais próximo com sua especificação OpenAPI:

  • Cenário 1:
    • Comportamento anterior:se a especificação OpenAPI exigisse um corpo de resposta, mas a resposta real da política de destino ou upstream não incluísse um, a política não sinalizaria isso como um erro de validação.
    • Comportamento atual: agora, a política retorna corretamente um erro de validação (por exemplo, defines a response schema but no response body found) nesse cenário, indicando uma incompatibilidade entre a resposta esperada e a real.
  • Cenário 2:
    • Comportamento anterior:se a especificação OpenAPI declarasse explicitamente que nenhum corpo de resposta era esperado, mas a resposta real da política de destino ou upstream incluísse um corpo, a política não resultaria em uma falha.
    • Comportamento atual:agora, a política vai resultar em uma falha (exemplo: No response body is expected but one was found) nesse cenário, garantindo que as respostas sigam estritamente o esquema especificado.

Mitigação

Identifique proxies ou fluxos compartilhados em que a política de validação do OAS está configurada com uma tag Source definida como response ou que validam a resposta de qualquer outra política que gera uma resposta.

Depois que um proxy/fluxo compartilhado é identificado, verifique o alinhamento entre a resposta e a especificação do OAS. A resposta precisa estar estritamente alinhada à sua especificação OpenAPI quanto à presença ou ausência de um corpo de resposta. Use o rastreamento padrão da Apigee para analisar seus padrões de tráfego. Se o destino estiver retornando a resposta de forma intermitente, use outras políticas para validá-la antes da política do OAS.

  • Se o arquivo de especificação OAS definir um corpo de resposta, a resposta da política de destino ou upstream sempre vai precisar fornecer um.
  • Se o arquivo de especificação da OAS não definir um corpo de resposta, a política de destino ou upstream não poderá enviar um.

Atualize a política de validação do OAS ou o comportamento de destino conforme necessário antes de tentar fazer upgrade para a nuvem privada 4.53.01. Primeiro, valide esses fluxos de trabalho identificados nos seus ambientes de não produção para minimizar o risco de interrupções durante o upgrade do cluster de produção.

Caminho JSON

Contexto

O Edge para nuvem privada 4.53.01 introduziu mudanças na forma como as expressões de caminho JSON são usadas em várias políticas. As expressões JSONPath podem ser usadas em políticas como ExtractVariable, RegularExpressionProtection e Mascaramento de dados para analisar conteúdo JSON ou armazenar valores em variáveis. As expressões JSONPath também podem ser usadas no modelo de mensagens geral para substituir variáveis por valores dinamicamente durante a execução do proxy. As novas expressões e formatos JSONPath seguem os padrões mais recentes de expressões JSON.

Mudanças

É importante analisar os proxies de API/fluxos compartilhados atuais para políticas que usam expressões JSONPath. Isso inclui, entre outras, a política de extração de variáveis, a política de proteção de expressão regular ou qualquer política com modelo de mensagem usando JSONPath.

A entrada JSON abaixo é usada para explicar as mudanças:

{
  "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. Mudança no comportamento do caractere curinga [*] do JSONPath para valores de objeto

    O comportamento do curinga [*] foi alterado quando usado para acessar todos os valores imediatos de um objeto JSON. Antes, $.object[*] retornava os valores imediatos envolvidos em um único objeto JSON. Com as bibliotecas atualizadas, a saída agora é uma matriz que contém esses valores.

    Por exemplo, $.store[*]:

    Comportamento anterior: 
    {
  "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"}
  ]
}
    Comportamento atual: 
    [
  [
    {"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"}]
  }
]
    Ação:

    Mude a expressão JSONPath para segmentar apenas o objeto pai (exemplo: $.store) e segmentar diretamente os itens recuperados anteriormente.

  2. O ponto final (.) no final do JSONPath em caminhos causa erro

    Há uma validação mais rigorosa para expressões JSONPath. Antes, os caminhos que terminavam com um ponto final inválido (por exemplo, $.path.to.element.) eram ignorados silenciosamente, e a consulta ainda retornava um resultado se o segmento de caminho válido anterior correspondesse. Com a nova versão, esses caminhos malformados agora são identificados corretamente como inválidos e resultam em um erro.

    Por exemplo, $.store.book..

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

    Todas as políticas atuais que usam expressões JSONPath com um ponto final não intencional vão falhar com um InvalidPathException.

    Ação:

    Remova o ponto final de qualquer expressão JSONPath que termine com um. Por exemplo, mude $.store.book. para $.store.book.

  3. Mudança na estrutura de saída do (..) de descida recursiva do JSONPath

    Há mudanças na forma como os resultados são retornados ao usar o operador (..) (descida recursiva) para localizar todas as ocorrências de um elemento nomeado. Antes, todos os elementos encontrados eram nivelados em uma única lista. As bibliotecas atualizadas agora retornam uma lista de listas, preservando a estrutura de agrupamento original em que os elementos foram encontrados, em vez de uma única lista simples.

    Por exemplo, $..book.

    Comportamento anterior: 
    [
  {"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"}
]
    Comportamento atual: 
    [
  [
    {"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"}
  ]
]
    Ação:

    Atualize a lógica de processamento downstream para considerar a nova estrutura de matriz aninhada. Provavelmente, você vai precisar iterar pelo JSONArray externo e, em seguida, por cada JSONArray interno para acessar os elementos individuais.

  4. Indexação JSONPath após seleção de vários itens ou filtro retorna matriz vazia

    Há uma mudança no comportamento quando um índice (exemplo: [0]) é aplicado imediatamente após um seletor de vários itens (como [*]) ou um filtro ([?(condition)]). Antes, essas expressões tentavam selecionar o item no índice especificado dos resultados combinados. Com a nova versão, essas expressões vão retornar uma matriz vazia ([]).

    Por exemplo, $.store.book[*][0].

    Comportamento anterior: 
    {"category": "reference", "price": 8.95, "author": "Nigel Rees"}
    Comportamento atual: 
    []
    Ação:

    Se for necessário filtrar e depois extrair um item específico do conjunto filtrado, processe a matriz filtrada retornada pelo JSONPath, por exemplo, $..book[?(@.category == 'fiction')], e extraia [0] do resultado anterior.

  5. Mudança na saída de segmentação de matriz negativa do JSONPath

    A nova versão modificou o comportamento do corte de matrizes negativas (exemplo: [-2:], [-1:]). Antes, ao aplicar um corte negativo a uma matriz (indicando elementos do final da matriz), a versão antiga retornava incorretamente apenas um único item desse corte. A nova versão agora retorna corretamente uma lista (matriz) com todos os elementos que estão dentro do intervalo negativo especificado.

    Por exemplo $.store.book[-2:]

    Comportamento anterior: 
    {"price":12.99,"category":"fiction","author":"Evelyn Waugh"}
    Comportamento atual: 
    [
  {"category":"fiction","author":"Evelyn Waugh","price":12.99},
  {"category":"fiction","author":"Herman Melville","price":8.99}
]
    Ação:

    A lógica de processamento downstream precisa ser atualizada para iterar pela matriz JSON retornada e gerar a saída desejada.

  6. Ponto anterior mais estrito do JSONPath

    Há uma aplicação mais rigorosa da sintaxe para elementos acessados diretamente da raiz. Quando os elementos são acessados diretamente da raiz sem um ponto anterior (exemplo: $propertyelement), essa sintaxe agora é considerada um erro e impede a implantação do proxy.

    Por exemplo, $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"}
  ]
}

    Comportamento atual:

    Proxy will fail to deploy.

    Ação:

    Mude seu JSONPath para incluir o ponto: $.propertyName (exemplo: $.store). Isso vai segmentar e recuperar o valor corretamente.

  7. Expressões JSONPath dinâmicas

    Preste atenção às políticas em que a própria expressão JSONPath é fornecida por uma variável (exemplo: {myJsonPathVariable} ou {dynamicPath}). O valor dessas variáveis também precisa ser verificado em relação às possíveis mudanças de comportamento descritas acima.

Mitigação

Para mitigar, é necessária uma estratégia abrangente. Esse processo envolve decidir o caminho de atualização adequado e aplicar a correção necessária para interromper as expressões JSONPath.

Escolha o método de upgrade que funciona melhor para você:

  • Migração sem inatividade

    Essa estratégia envolve a aquisição de um ou mais ambientes novos para que você possa conectar nós separados do processador de mensagens a eles. Esses nós de processador de mensagens podem ser configurados para instalar a versão 4.53.01 e ter proxies com expressões JSONPath modernas. Eles podem ser usados durante o upgrade e desativados após a conclusão. Essa estratégia é perfeita, mas envolve a aquisição temporária de nós extras de processador de mensagens para oferecer suporte a uma atualização tranquila. Detalhes abaixo:

    • Crie um novo ambiente e adicione novos nós de processador de mensagens da versão 4.53.01 a ele.
    • Faça upload do pacote de proxy para os proxies afetados no novo ambiente, aplique as correções necessárias explicadas na seção de correção e implante o pacote de proxy atualizado no novo ambiente.
    • Redirecione o tráfego para o novo ambiente e cancele a implantação dos proxies afetados no ambiente antigo.
    • Faça upgrade dos nós originais do processador de mensagens para a versão 4.53.01. Implante proxies com correções para JSONPath no ambiente original.
    • Mude o tráfego de volta para o ambiente antigo, que agora tem processadores de mensagens na versão 4.53.01 e um proxy modernizado para novas expressões jsonpath.
    • Exclua e desative o novo ambiente e os nós associados.
  • Tempo de inatividade e upgrade

    Essa estratégia envolve a aquisição de tempo de inatividade para proxies de API usando expressões de caminho JSON com falha. Não é necessário adquirir mais nós de processador de mensagens, mas isso causa interrupção no tráfego da API para proxies afetados.

    • Identifique os proxies afetados com políticas afetadas e gere uma nova revisão para todos eles.
    • Aplique as correções necessárias implementando as correções explicadas na seção de correção em uma nova revisão do proxy. Não implante ainda.
    • Procure um tempo de inatividade para o proxy ou os proxies afetados.
    • Faça upgrade de todos os processadores de mensagens para a versão 4.53.01 do Edge para nuvem privada. Os proxies atuais podem falhar nos processadores de mensagens recém-atualizados.
    • Depois que todos os processadores de mensagens forem atualizados para a versão 4.53.01 do Edge para nuvem privada , implante a revisão de proxy recém-criada com a expressão JSONPath corrigida.
    • Retome o tráfego nesses proxies.
  • Redesenhar o proxy antes do upgrade

    É possível redesenhar o próprio proxy antes de fazer upgrade para o Edge para nuvem privada 4.53.01. Em vez de usar expressões de caminho JSON específicas, você pode ter o mesmo resultado usando um método diferente.

    Por exemplo, se você estiver usando uma política de extração de variáveis com um caminho JSON, poderá substituir a política por uma política JavaScript que extraia dados semelhantes antes de fazer upgrade para a versão mais recente. Depois que o upgrade for concluído, você poderá mudar o proxy de volta para usar caminhos JSON com formatos mais recentes.

Mudanças no JavaCallout

Contexto

O Edge para nuvem privada 4.53.00 e versões anteriores continha um diretório chamado deprecated ($APIGEE_ROOT/edge-message-processor/lib/deprecated) com várias bibliotecas JAR. Essas bibliotecas estavam disponíveis para uso em código Java na política JavaCallout e podiam ser usadas diretamente ou indiretamente pelo seu código Java personalizado.

Mudanças

O diretório descontinuado foi removido da versão 4.53.01 do Edge para nuvem privada. Caso seu código Java dependa dessas bibliotecas, os proxies que usam essas chamadas Java vão falhar quando os processadores de mensagens forem atualizados para a versão 4.53.01. Para evitar essas falhas, siga as etapas de mitigação abaixo antes de fazer upgrade dos processadores de mensagens para a versão 4.53.01.

Mitigação

  1. Revise suas políticas de JavaCallout e os jars associados e identifique se algum deles faz referência ou usa bibliotecas presentes no diretório "deprecated" dos seus processadores de mensagens atuais. As chamadas Java podem estar usando jars enviados como recursos no nível da organização ou do ambiente. Considere também estas bibliotecas.
  2. Depois de identificar essas bibliotecas descontinuadas , siga um dos métodos abaixo para mitigar o problema.
    • Posicionamento de recursos (recomendado se você tiver um pequeno número de jars / bibliotecas do diretório descontinuado que estão sendo referenciados pelos jars de destaque do Java)
      • Faça upload dos jars descontinuados identificados como um recurso no nível desejado: revisão do proxy da API, ambiente ou organização.
      • Continue com o upgrade do software da Apigee normalmente.
    • Posicionamento manual (recomendado se você tiver um grande número de jars / bibliotecas referenciados pelos jars de callout do Java)
      • Em cada nó do processador de mensagens, crie um diretório chamado external-lib no caminho $APIGEE_ROOT/data/edge-message-processor/.
      • Copie os JARs identificados para o diretório external-lib do diretório descontinuado: cp $APIGEE_ROOT/edge-message-processor/lib/deprecated/some.jar $APIGEE_ROOT/data/edge-message-processor/external-lib/some.jar
      • Verifique se o diretório e os jars subjacentes podem ser lidos pelo usuário da Apigee: chown -R apigee:apigee $APIGEE_ROOT/data/edge-message-processor/external-lib
      • Continue com o upgrade do software da Apigee normalmente.

Mudança no OpenLDAP

Contexto

O OpenLDAP pode ser usado na nuvem privada do Edge para autenticação e autorização. No Edge para nuvem privada 4.53.01, o software OpenLDAP enviado pela Apigee foi atualizado da versão 2.4 para a 2.6.

Mudanças

No OpenLDAP 2.6, o nome distinto relativo (RDN) é limitado a aproximadamente 241 bytes/caracteres. Essa limitação é um limite máximo imposto e não pode ser modificada.

Impacto
  • Falhas de replicação ou importação ocorrem para entradas com RDNs excessivamente grandes.
  • A tentativa de criar entidades como organizações,ambientes, papéis personalizados, permissões etc. pode resultar na mensagem de erro: "message": "[LDAP: error code 80 - Other]".
  • Qualquer DN com mais de 241 bytes no LDAP da Apigee é afetado. Esses DNs impedem o upgrade do software OpenLDAP do Apigee, e você precisa seguir estratégias de mitigação para esses itens antes de continuar com o upgrade.

Em geral, no LDAP da Apigee, os DNs longos estão relacionados a permissões, já que são criados concatenando várias entidades. Essas entradas de permissão são especialmente propensas a problemas de upgrade.

Por exemplo, 

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

Normalmente, os nomes de organização, ambiente e função têm tamanhos que fazem com que os RDNs no LDAP sejam menores que 241 bytes.

Mitigação

Antes do upgrade para a versão 4.53.01:

As etapas a seguir ajudam a verificar a presença de RDNs longos no cluster LDAP 2.4 atual.

1. Extrair dados do LDAP

Use o comando ldapsearch para encontrar o nome distinto (dn) e redirecione a saída para um arquivo: 

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

Verifique se o arquivo DN.ldif acima tem entradas LDAP.

#2: identifique RDNs longos

Encontre os RDNs que excedem 241 bytes/caracteres no arquivo DN.ldif acima:

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)

Se o comando acima não produzir saída, nenhum RDN na configuração LDAP atual excederá 241 bytes/caracteres. Você pode continuar com o upgrade normalmente.

Se o comando acima gerar uma saída, isso indica a presença de RDNs que excedem 241 bytes/caracteres. Para esses itens, siga as etapas de mitigação descritas na etapa 3 antes de continuar com o upgrade do Edge para nuvem privada 4.53.01.

Nº 3: processar RDNs longos

Se você receber uma saída da etapa 2, isso indica a presença de RDNs com mais de 241 bytes/caracteres. Siga as etapas de mitigação abaixo:

Revise as entradas LDAP que excedem 241 bytes.

  • Se for o nome da função personalizada, do app, do produto da API ou de outras entidades que é o principal fator para o RDN ser longo, migre para usar uma entidade alternativa com um nome mais curto.
  • Se o nome da organização ou do ambiente for o principal contribuinte para o RDN longo, migre para outra organização ou ambiente com um nome mais curto.

Repita as etapas acima até que seu LDAP não tenha RDNs maiores que 241 bytes. Quando você atingir esse estado, continue com o upgrade da versão da nuvem privada normalmente.

Mudanças no provedor de criptografia

Contexto

Essa mudança é uma transferência do Edge para nuvem privada 4.53.00. No Edge para nuvem privada 4.53.00, o provedor de criptografia interna foi atualizado do Bouncy Castle (BC) para o Bouncy Castle FIPS (BCFIPS) para ativar a compatibilidade com FIPS.

Mudanças

Se as políticas JavaCallout dependerem do uso do provedor BC original, especialmente ao usar funcionalidades de segurança reforçadas no provedor BCFIPS (por exemplo, usando um par de chaves comum para criptografia e assinatura), essas políticas JavaCallout precisarão ser modernizadas. As políticas JavaCallout que tentam carregar o provedor de criptografia Bouncy Castle usando o nome BC podem falhar porque o provedor padrão mudou. Essas políticas que usam o provedor BC podem falhar posteriormente. Todas as implementações personalizadas que dependem do provedor BC antigo não estarão mais acessíveis e precisarão ser revisadas e reimplementadas.

Mitigação

A solução alternativa recomendada é usar o provedor BCFIPS. As implementações personalizadas de JavaCallout que dependiam do provedor antigo precisam ser revisadas e reimplementadas usando o provedor Bouncy Castle FIPS, que pode ser acessado usando a string "BCFIPS".

Ferramenta automatizada de detecção de mudanças

Uma ferramenta de detecção de mudanças será lançada em breve. Essa ferramenta pode verificar e identificar proxies de API, fluxos compartilhados, recursos e RDNs LDAP que podem ser afetados por várias mudanças descritas neste artigo. Essa ferramenta ajuda a identificar várias entidades propensas a falhas durante ou após o upgrade para o Edge para nuvem privada 4.53.01.