Opções para configurar o TLS

Esta é a documentação do Apigee Edge.
Acesse 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.

&lt;CommonName&gt;

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 as configurações do VirtualHost.

Por padrão, o valor especificado corresponde exatamente ao nome real do certificado de destino. Por exemplo, usar *.myhost.com como o valor de <CommonName> só vão 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.

Como alternativa, 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 seria correspondido e validado se o elemento <CommonName> é especificado da seguinte forma:

<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 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, é 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 entre em contato com o suporte do Apigee Edge.
  • Para clientes da nuvem privada: alterar o valor da referência não exigem 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 entre em contato com o suporte do Apigee Edge e os clientes da nuvem privada precisam reiniciar determinados 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 da 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, não será possível usar as referências do keystore e truststore em hosts virtuais.

Se o host virtual atual usa um keystore ou nome de 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 para a nuvem

    Para alterar o host virtual para usar uma referência ao keystore com que você precisa trabalhar Suporte do Apigee Edge.

  2. Edge para a nuvem privada

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

    1. Atualizar 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 um para a nuvem privada.

Sobre como usar a chave e o certificado de teste sem custo financeiro da Apigee

Se você tiver uma conta paga do Edge para Cloud e ainda não tiver uma chave e um certificado TLS, crie um host virtual que usa a chave e o certificado de teste 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 a chave e o certificado de teste sem custo financeiro da Apigee omite o <KeyStore> e <KeyAlias> e os substitui pelos <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 a configuração do TLS é executada:

  • Você é cliente do Edge Cloud ou da nuvem privada?
  • Como você vai atualizar certificados expirados ou que estão 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 o Cloud e a nuvem privada clientes:

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 de hosts virtuais e endpoints de destino/servidores de destino. Esse controle inclui a capacidade de criar e excluir e defina 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 do endpoints de destino/servidores de destino. Além disso, os clientes pagos do Cloud têm controle total hosts virtuais, incluindo propriedades 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, como descrito nas tabela a seguir. Como você pode ver, as referências oferecem a maior flexibilidade para o Cloud Clientes da nuvem privada:

Tipo de configuração Como atualizar/substituir certificado Nuvem privada Cloud
Referência (recomendado) No caso de keystore, crie um novo keystore com um novo nome e um alias com 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 reiniciar o Roteador ou o Processador de mensagens.

Atualize a referência do keystore ou 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 o var de fluxo atualizado em 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 o var de fluxo atualizado 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, 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 falham 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 endpoint/servidor de destino de destino, reinicie a mensagem Processadores.

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.