Opções para configurar o TLS

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Esta seção mostra como configurar o TLS para tráfego de um proxy para um destino.

Sobre a definição de opções de TLS em um endpoint ou servidor de destino

Um destino pode ser representado por um objeto XML como este:

<HTTPTargetConnection>
    <Properties/>
    <URL>https:myTargetAddress</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <Enforce>true</Enforce>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://myKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://myTruststoreRef</TrustStore>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
        <Protocols>myProtocols</Protocols>
        <Ciphers>myCipher</Ciphers>
    </SSLInfo>
</HTTPTargetConnection>

A área da configuração do endpoint de destino que você modifica para configurar o TLS é definida pela tag <SSLInfo>. Use a mesma tag <SSLInfo> para configurar um endpoint ou servidor de destino.

Para saber mais sobre os elementos filhos de <SSLInfo>, consulte Configuração de TargetEndpoint de TLS/SSL.

A tabela a seguir descreve os elementos de configuração do TLS usados pela tag <SSLInfo>:

Elemento	Descrição
`<Enabled>`	O bloco `<SSLInfo>` pode ser usado para TLS/SSL unidirecional e bidirecional. Se definido como `true`, `<Enabled>` especificará que o bloco `<SSLInfo>` precisa ser usado. Quando definido como `false`, o bloco `<SSLInfo>` é ignorado. O valor padrão de `<Enabled>` é `true` se `<URL>` especificar o protocolo HTTPS e `false` se `<URL>` especificar HTTP.
`<Enforce>`	Aplica SSL rigoroso entre a Apigee e o back-end de destino. Se definidas como `true`, as conexões falharão para destinos com certificados inválidos, certificados expirados, certificados autoassinados, certificados com uma incompatibilidade de nome do host e certificados com uma raiz não confiável. Um código de falha `4xx` ou `5xx` é retornado. Se não for definido ou for definido como `false`, o resultado das conexões para back-ends de destino com certificados problemáticos dependerá da configuração de `<IgnoreValidationErrors>`. Confira abaixo. Uma resposta de sucesso (`2xx`) poderá ocorrer em determinadas condições, se `<IgnoreValidationErrors>` estiver definido como `true`.
`<ClientAuthEnabled>`	Ativa o TLS bidirecional (também conhecido como TLS mútuo ou mTLS) entre a Apigee e o cliente da API ou entre a Apigee e o back-end de destino. A ativação do TLS bidirecional exige que você configure um truststore na Apigee e um truststore.
`<KeyStore>`	Um keystore com chaves privadas usadas para autenticação do cliente de saída
`<KeyAlias>`	O alias especificado quando você fez upload de um certificado e uma chave privada para o armazenamento de chaves.
`<TrustStore>`	Um keystore com certificados de servidor confiáveis.
`<IgnoreValidationErrors>`	Indica se os erros de validação são ignorados. Se o sistema de back-end usar SNI e retornar um certificado com um nome distinto (DN, na sigla em inglês) de assunto que não corresponda ao nome do host, não será possível ignorar o erro, e a conexão falhará. Observação: se `<Enforce>` for definido como `true`, o valor de `<IgnoreValidationErrors>` será ignorado.
`<Ciphers>`	Criptografias compatíveis para TLS/SSL de saída. Se nenhuma criptografia for especificada, todas as criptografias disponíveis para o JVM serão permitidas. Para restringir as criptografias, adicione os elementos a seguir listando as criptografias compatíveis: <Ciphers> <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher> <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher> </Ciphers>
`<Protocols>`	Protocolos compatíveis com TLS/SSL de saída. Se nenhum protocolo for especificado, todos os protocolos disponíveis para JVM serão permitidos. Para restringir protocolos, especifique-os explicitamente. Por exemplo, para permitir apenas TLS v1.2 ou TLS v1.3: <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols>

Sobre a configuração dos elementos <KeyStore> e <TrustStore>

No exemplo acima, o keystore e o truststore são especificados usando referências, no formato:

<KeyStore>ref://myKeystoreRef</KeyStore>
<TrustStore>ref://myTruststoreRef</TrustStore>

A Apigee recomenda que você sempre use referências ao keystore e ao truststore. Uma referência é uma variável que contém o nome do keystore ou do truststore, em vez de especificar o nome do keystore diretamente. Neste exemplo:

myKeystoreRef é uma referência que contém o nome do keystore. Neste exemplo, o nome do keystore é myKeystore.
myTruststoreRef é uma referência que contém o nome do truststore. Neste exemplo, o nome do truststore é myTruststore.

Quando um certificado expira, você precisa atualizar o endpoint/servidor de destino para especificar o keystore ou o truststore que contém o novo certificado. A vantagem de uma referência é que ela permite modificar o valor da referência para alterar o keystore ou o truststore sem precisar modificar o endpoint de destino/servidor de destino:

Alterar o valor da referência não requer que você entre em contato com o Suporte do Google Cloud.

Como alternativa, é possível especificar o nome do keystore e o nome do truststore diretamente:

<KeyStore>myKeystore</KeyStore>
<TrustStore>myTruststore</TrustStore>

Se você especificar diretamente o nome do keystore ou do truststore, entre em contato com o Suporte do Google Cloud.

Uma terceira opção é usar variáveis de fluxo:

<KeyStore>{ssl.keystore}</KeyStore>
<TrustStore>{ssl.truststore}</TrustStore>

As variáveis de fluxo funcionam para atualizar o keystore ou o truststore como referências. Para mais informações, consulte Como usar variáveis de fluxo para definir valores TLS/SSL dinamicamente.

Sobre a configuração do TLS

Todos os clientes da Apigee, pagos e de avaliação, têm controle total sobre a configuração dos endpoints/servidores de destino. Além disso, os clientes pagos da Apigee têm controle total sobre as propriedades do TLS.

Como processar certificados expirados

Se um certificado TLS expirar ou se a configuração do sistema mudar para que o certificado não seja mais válido, será necessário atualizar o certificado. Ao configurar o TLS para um endpoint de destino/servidor de destino, decida como você executará essa atualização antes de realizar qualquer configuração.

Quando um certificado expira

Na Apigee, você armazena certificados em um destes dois locais:

Keystore: contém o certificado TLS e a chave privada usados para identificar a entidade durante o handshake de TLS.
Truststore: contém certificados confiáveis em um cliente TLS, usado para validar o certificado de um servidor TLS apresentado ao cliente. Em geral, esses certificados são autoassinados, assinados por uma AC confiável ou usados como parte do TLS bidirecional (também conhecido como TLS mútuo ou mTLS).

Quando um certificado de um keystore expira e você está usando uma referência a ele, não será possível fazer upload de um novo certificado para o keystore. Em vez disso, você precisa:

Criar um novo repositório de chaves.
Fazer upload do novo certificado para o novo armazenamento de chaves usando o mesmo nome de alias que o keystore antigo.
Atualize a referência no servidor de destino/endpoint de destino para usar o novo keystore.

Quando um certificado em um truststore expira e você está usando uma referência ao truststore, você:

Crie um novo truststore.
Faça upload do novo certificado para o novo truststore. O nome do alias não importa para truststores. Observação: se um certificado fizer parte de uma cadeia, você precisará criar um único arquivo contendo todos os certificados e fazer o upload desse arquivo para um único alias ou fazer o upload de todos os certificados da cadeia separadamente para o truststore usando um alias diferente para cada certificado.
Atualize a referência no servidor de destino/endpoint de destino para utilizar o novo truststore.

Resumo dos métodos de atualização de um certificado expirado

O método usado para especificar o nome do keystore e truststore no endpoint de destino/servidor de destino determina como você executa a atualização do certificado. Você pode usar:

Referências
Nomes diretos
Variáveis de fluxo

Cada um desses métodos tem diferentes repercussões no processo de atualização, conforme descrito na tabela a seguir:

Tipo de configuração	Como atualizar/substituir certificado	Uso
Referência (recomendado)	No caso de keystore, crie um keystore com um novo nome e um alias com o mesmo nome do antigo. Para uma truststore, crie um truststore com um novo nome.	Atualize a referência do keystore ou truststore. Não é necessário entrar em contato com o suporte da Apigee.
Variável de fluxo	Para um keystore, crie um keystore com um novo nome e um alias com o mesmo nome ou com um novo nome. Para uma truststore, crie um truststore com um novo nome.	Transmita a variável de fluxo atualizada em cada solicitação com o nome do novo keystore, alias ou truststore. Não é necessário entrar em contato com o suporte da Apigee.
Direta	Crie um novo keystore, alias e truststore.	Implante o proxy novamente.
Direta	Exclua o keystore ou o truststore e crie-o novamente com o mesmo nome.	As solicitações de API falharão até que os novos keystore e alias sejam definidos. Se o keystore for usado para TLS bidirecional (também conhecido como TLS mútuo ou mTLS) entre a Apigee e o serviço de back-end, entre em contato com o Suporte do Google Cloud para reiniciar os processadores de mensagens.
Direta	Apenas para truststore, faça upload de um novo certificado para o truststore.	Entre em contato com o Suporte do Google Cloud para reiniciar os processadores de mensagens.