Opções para configurar o TLS

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Neste documento, você terá uma visão geral de como configurar o TLS no Edge para duas áreas funcionais:

  1. Acesso aos seus proxies de API por clientes de API. Use hosts virtuais no Edge Router para configurar o TLS.
  2. Acesso aos serviços de back-end pelo Edge. Use endpoints de destino e servidores de destino no Edge Message Processor para configurar o TLS.

Esses dois tipos de acesso são mostrados abaixo:

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

Um host virtual pode ser representado por um objeto XML na forma:

<VirtualHost name="secure">
    ...
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://myKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://myTruststoreRef</TrustStore> 
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

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

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 o Edge e o cliente da API ou entre o Edge e o back-end de destino.

Para um host virtual, você precisa definir um keystore que contenha o certificado e a chave privada.

<ClientAuthEnabled>

Ativa o TLS bidirecional entre o Edge e o cliente da API ou entre o Edge e o back-end de destino.

A ativação do TLS bidirecional normalmente exige que você configure um truststore no Edge.

<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, o Edge ignora os erros de certificado TLS. Válido ao configurar o TLS para servidores de destino e endpoints de destino, além de configurar hosts virtuais que usam TLS bidirecional. O valor padrão é falso.

Quando usado com um endpoint de destino/servidor de destino, 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 falha.

<CommonName>

Se especificado, um valor em relação ao qual o nome comum do certificado de destino é validado. Este valor só é válido para as configurações TargetEndpoint e TargetServer. Não é válido para configurações do VirtualHost.

Por padrão, o valor especificado é correspondido exatamente ao nome comum do certificado de destino. Por exemplo, usar *.myhost.com como o valor de <CommonName> só vai corresponder e validar o nome do host de destino se o valor exato *.myhost.com for especificado como o nome comum no certificado de destino.

Opcionalmente, a Apigee pode fazer a correspondência com caracteres curinga usando o atributo wildcardMatch.

Por exemplo, um nome comum especificado como abc.myhost.com em um certificado de destino será correspondido e validado se o elemento <CommonName> for especificado da seguinte maneira:

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

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

No exemplo de host virtual acima, o keystore e o truststore são especificados usando references, 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, é necessário atualizar o host virtual ou 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 você pode modificar o valor da referência para alterar o keystore ou o truststore sem precisar modificar o host virtual ou o servidor de destino/servidor de destino:

  • Para clientes do Cloud: alterar o valor da referência não exige que você entre em contato com o suporte do Apigee Edge.
  • Para clientes de nuvem privada: alterar o valor da referência não exige que você reinicie os componentes do Edge, como roteadores e processadores de mensagens.

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, os clientes do Cloud precisarão entrar em contato com o suporte do Apigee Edge e os clientes da nuvem privada precisarão reiniciar alguns componentes do Edge para atualizar o certificado.

Uma terceira opção, apenas para endpoints de destino/servidor de destino, é usar variáveis de fluxo:

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

As variáveis de fluxo funcionam para endpoints de destino/servidores de destino e permitem que você atualize o keystore ou o truststore, como referências. No entanto, eles não funcionam com hosts virtuais e exigem que você transmita informações sobre o keystore, o alias e o truststore em cada solicitação.

Restrições ao usar referências a keystores e truststore

Os clientes de nuvem paga e todos os clientes da nuvem privada que configuram o TLS precisam considerar a seguinte restrição ao usar referências a keystores e truststores:

  • Só é possível usar as referências a keystore e truststore em hosts virtuais se você encerrar o TLS nos roteadores da Apigee.
  • Se você tiver um balanceador de carga na frente dos roteadores da Apigee e encerrar o TLS no balanceador de carga, não será possível usar referências de keystore e truststore em hosts virtuais.

Se o host virtual atual usa um nome de keystore literal ou truststore

Os hosts virtuais atuais do Edge não podem ser configurados para usar referências a keystores e truststores. Nesse caso, é possível atualizar o host virtual para usar uma referência.

  1. Edge for the Cloud (em inglês)

    Para alterar o host virtual para usar uma referência ao keystore, trabalhe com o suporte do Apigee Edge.

  2. Edge para a nuvem privada

    Para converter o host virtual para usar uma referência:

    1. Atualize o host virtual para usar uma referência.
    2. Reinicie os roteadores.
    Consulte "Como modificar um host virtual para usar referências ao keystore e ao truststore" em Como configurar o acesso TLS a uma API para a nuvem privada para saber mais.

Sobre o uso da chave e do certificado de avaliação sem custo financeiro da Apigee

Se você tiver uma conta paga do Edge para a nuvem e ainda não tiver um certificado e uma chave TLS, crie um host virtual que use o certificado e a chave de avaliação sem custo financeiro da Apigee. Isso significa que você pode criar o host virtual sem primeiro criar um keystore.

Um objeto XML que define o host virtual usando o certificado e a chave do teste sem custo financeiro da Apigee omite os elementos <KeyStore> e <KeyAlias> e os substitui pelo elemento <UseBuiltInFreeTrialCert>, conforme mostrado abaixo:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

Se você estiver executando o TLS bidirecional, ainda precisará definir o elemento <ClientAuthEnabled> como true e especificar um truststore usando uma referência com o elemento <TrustStore> para criar um anexo da VLAN de monitoramento.

Consulte Como configurar hosts virtuais para a nuvem para mais informações.

Sobre a configuração do TLS

Dois fatores principais determinam como você executa a configuração do TLS:

  • Você é cliente de nuvem privada ou de nuvem privada?
  • Como você vai atualizar os certificados expirados ou prestes a expirar?

Opções de configuração de nuvem e nuvem privada

A tabela a seguir mostra as diferentes opções de configuração para clientes do Google Cloud e da nuvem privada:

Nuvem privada Cloud
Host virtual Controle total Controle total apenas para contas pagas
Endpoint de destino/servidor de destino Controle total Controle total

Os clientes da nuvem privada têm controle total sobre a configuração dos hosts virtuais e dos endpoints/servidores de destino. Esse controle inclui a capacidade de criar e excluir hosts virtuais e definir todas as propriedades em um host virtual.

Todos os clientes do Cloud, pagos e de avaliação, têm controle total sobre a configuração de endpoints/servidores de destino. Além disso, os clientes pagos do Cloud têm controle total de hosts virtuais, incluindo propriedades de 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 host virtual ou um endpoint/servidor de destino, decida como executar essa atualização antes de realizar qualquer configuração.

Quando um certificado expira

No Edge, 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. Esses certificados normalmente são certificados autoassinados, certificados assinados por uma CA confiável ou certificados usados como parte do TLS bidirecional.

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:

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

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

  1. Crie um novo truststore.
  2. 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 um alias diferente para cada certificado.
  3. Atualize a referência no host virtual ou no endpoint de destino/servidor para usar 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 host virtual ou 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 repercussões diferentes no processo de atualização, conforme descrito na tabela a seguir. Como você pode notar, as referências oferecem a maior flexibilidade para clientes do Cloud e da nuvem privada:

Tipo de configuração Como atualizar/substituir certificado Nuvem privada Cloud
Referência (recomendado) Para um keystore, crie um novo keystore com um novo nome e um alias com o mesmo nome do alias antigo.

Para uma truststore, crie um truststore com um novo nome.

Atualize a referência para o keystore ou o truststore.

Não é necessário reiniciar o roteador ou o processador de mensagens.

Atualize a referência para o keystore ou o truststore.

Não é necessário entrar em contato com o suporte da Apigee.

Variáveis de fluxo (somente endpoint de destino) Para um keystore, crie um novo 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 a cada solicitação com o nome do novo keystore, alias ou truststore.

Não é necessário reiniciar o roteador ou o processador de mensagens.

Transmita a variável de fluxo atualizada a 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, truststore. Atualize o host virtual e reinicie os roteadores.

Se o truststore for usado por um endpoint/servidor de destino, reimplante o proxy.

No caso de hosts virtuais, entre em contato com o suporte do Apigee Edge para reiniciar os roteadores.

Se o truststore for usado por um endpoint/servidor de destino, reimplante o proxy.

Direto Exclua o repositório de chaves ou o truststore e recrie-o com o mesmo nome. Não é necessário atualizar o host virtual nem reiniciar o roteador. No entanto, as solicitações de API apresentarão falha até que o novo keystore e o alias sejam definidos.

Se o keystore for usado para TLS bidirecional entre o Edge e o serviço de back-end, reinicie os processadores de mensagens.

Não é necessário atualizar o host virtual. No entanto, as solicitações de API falharão até que o novo keystore e o alias sejam definidos.

Se o keystore for usado para TLS bidirecional entre o Edge e o serviço de back-end, entre em contato com o suporte do Apigee Edge para reiniciar os processadores de mensagens.

Direto Apenas para truststore, faça upload de um novo certificado para o truststore. Se o truststore for usado por um host virtual, reinicie os roteadores.

Se o truststore for usado por um servidor de endpoint/destino de destino, reinicie os processadores de mensagens.

No caso de hosts virtuais, entre em contato com o suporte do Apigee Edge para reiniciar os roteadores de borda.

Se o truststore for usado por um endpoint/servidor de destino de destino, entre em contato com o suporte do Apigee Edge para reiniciar os processadores de mensagens.