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>
    </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>`	Ativa o TLS unidirecional entre a Apigee e o cliente da API ou entre a Apigee e o back-end de destino.
`<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>`	O armazenamento de chaves.
`<KeyAlias>`	O alias especificado quando você fez upload de um certificado e uma chave privada para o armazenamento de chaves.
`<TrustStore>`	O truststore.
`<IgnoreValidationErrors>`	Se verdadeiro, a Apigee ignora os erros de certificado TLS. O valor padrão é falso. 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.

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:

Não é necessário entrar em contato com o suporte da Apigee para alterar o valor da referência.

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 da Apigee.

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.
Direto	Crie um novo keystore, alias e truststore.	Implante o proxy novamente.
Direto	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 da Apigee para reiniciar os processadores de mensagens.
Direto	Apenas para truststore, faça upload de um novo certificado para o truststore.	Entre em contato com o suporte da Apigee para reiniciar os processadores de mensagens.