Como configurar o TLS do Edge para o back-end (nuvem e nuvem privada)

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

Um proxy de API funciona como um mapeamento de um endpoint disponível publicamente para seu serviço de back-end. Um host virtual define a forma como o proxy de API voltado para o público é exposto a um app. Por exemplo, o host virtual determina se o proxy de API pode ser acessado usando TLS. Ao configurar um proxy de API, edite a definição de ProxyEndpoint para configurar os hosts virtuais que ele usa.

O TargetEndpoint é o equivalente de saída do ProxyEndpoint. Um TargetEndpoint funciona como um cliente HTTP do Edge para um serviço de back-end. Ao criar um proxy de API, é possível configurá-lo para usar zero ou mais TargetEndpoints.

Saiba mais:

Como configurar um TargetEndpoint ou TargetServer

Para configurar um TargetEndpoint, edite o objeto XML que define o TargetEndpoint. Para editar o TargetEndpoint, edite o arquivo XML que define o TargetEndpoint no proxy de API ou na IU de gerenciamento do Edge.

Para usar a IU de gerenciamento de borda para editar o TargetEndpoint:

  1. Faça login na IU de gerenciamento do Edge em https://enterprise.apigee.com.
  2. Selecione o nome do proxy de API a ser atualizado.
  3. Selecione a guia Desenvolver.
  4. Em Pontos de extremidade de destino, selecione padrão.
  5. Na área de código, a definição de TargetEndpoint aparece, semelhante a esta:
    <TargetEndpoint name="default">
      <Description/>
      <FaultRules/>
      <Flows/>
      <PreFlow name="PreFlow">
        <Request/>
        <Response/>
      </PreFlow>
      <PostFlow name="PostFlow">
        <Request/>
        <Response/>
      </PostFlow>
      <HTTPTargetConnection>
        <Properties/>
        <SSLInfo>
          <Enabled>true</Enabled>
          <TrustStore>ref://myTrustStoreRef</TrustStore>
        </SSLInfo>
        <URL>https://mocktarget.apigee.net</URL>
      </HTTPTargetConnection>
    </TargetEndpoint>
  6. Configure um truststore conforme descrito abaixo em Sobre a configuração de TLS com o back-end.
  7. Faça as alterações e salve o proxy. Se o proxy de API foi implantado, salvá-lo o reimplanta com a nova configuração.

Observe que a definição do TargetEndpoint contém uma propriedade name. Use o valor da propriedade name para configurar a definição de ProxyEndpoint de um proxy de API para usar o TargetEndpoint. Consulte a referência de configuração do proxy de API para mais informações.

O TargetEndpoints pode ser configurado para referenciar um TargetServer em vez do URL de destino explícito. Uma configuração do TargetServer separa os URLs concretos do endpoint das configurações do TargetEndpoint. Os TargetServers são usados para dar suporte ao balanceamento de carga e ao failover em várias instâncias do servidor de back-end.

Confira abaixo um exemplo de definição do TargetServer:

<TargetServer name="target1">
  <Host>mocktarget.apigee.net</Host>
  <Port>80</Port>
  <IsEnabled>true</IsEnabled>
</TargetServer> 

Um TargetServer é referenciado por nome no elemento <HTTPTargetConnection> em uma definição de TargetEndpoint. É possível configurar um ou mais TargetServers, conforme mostrado abaixo.

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <LoadBalancer>
      <Server name="target1" />
      <Server name="target2" />
    </LoadBalancer>
    <Path>/test</Path>
  </HTTPTargetConnection>
  ...
</TargetEndpoint>

Consulte Balanceamento de carga entre servidores de back-end para saber mais.

Sobre a configuração do TLS com o back-end

Antes de configurar o acesso TLS ao back-end, é preciso entender dois pontos importantes:

  1. Por padrão, o Edge não valida o certificado de back-end. É preciso criar um truststore para configurar o Edge para validar o certificado.
  2. Use uma referência para especificar o keystore ou o truststore usado pelo Edge.

As duas considerações são descritas abaixo.

Como definir um truststore para ativar a validação do certificado

Ao fazer uma solicitação TLS por um TargetEndpoint ou TargetServer, o Edge não valida, por padrão, o certificado TLS recebido do servidor de back-end. Isso significa que o Edge não valida que:

  • O certificado foi assinado por uma CA confiável.
  • O certificado não expirou.
  • O certificado apresenta um nome comum. Se houver um nome comum, o Edge não vai validar se o nome comum corresponde ao nome do host especificado no URL.

Para configurar o Edge para validar o certificado de back-end, é preciso:

  1. Criar um truststore no Edge.
  2. Faça upload do certificado ou da cadeia de certificados do servidor para o truststore. Se o certificado do servidor for assinado por terceiros, será necessário fazer upload da cadeia completa de certificados, incluindo o certificado da CA raiz, para o truststore. Não há CAs implicitamente confiáveis.
  3. Adicione o truststore à definição TargetEndpoint ou TargetServer.

Consulte Keystores e Truststores para saber mais.

Exemplo:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <TrustStore>ref://myTrustStoreRef</TrustStore>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

Como usar uma referência a um keystore ou truststore

O exemplo abaixo mostra como configurar um TargetEndpoint ou TargetServer para aceitar o TLS. Como parte da configuração do TLS, você especifica um truststore e um keystore como parte de uma definição TargetEndpoint ou TargetServer.

A Apigee recomenda altamente que você use uma referência ao keystore e ao truststore na definição de TargetEndpoints ou TargetServer. A vantagem de usar uma referência é que você só precisa atualizá-la para apontar para um keystore ou um truststore diferente para atualizar o certificado TLS.

As referências a keystores e truststores na definição TargetEndpoints ou TargetServer funcionam da mesma forma que para hosts virtuais.

Como converter um TargetEndpoint ou TargetServer para usar uma referência

É possível ter definições TargetEndpoint ou TargetServer que usam o nome literal do keystore e do truststore. Para converter a definição TargetEndpoint ou TargetServer para usar referências:

  1. Atualize a definição TargetEndpoint ou TargetServer para usar uma referência.
  2. Reinicie os processadores de mensagens de borda:
    • Para clientes de Nuvem pública, entre em contato com o suporte do Apigee Edge para reiniciar os processadores de mensagens.
    • Para clientes de nuvem privada, reinicie os processadores de mensagens de borda um de cada vez.
  3. Confirme se o TargetEndpoint ou o TargetServer está funcionando corretamente.

Configurar o TLS unidirecional para o servidor de back-end

Ao usar uma definição de TargetEndpoint, a configuração do acesso TLS unidirecional do Edge (cliente TLS) para o servidor de back-end (servidor TLS) não exige nenhuma configuração adicional no Edge. Cabe ao servidor de back-end configurar o TLS corretamente.

Você só precisa garantir que o elemento <URL> na definição do TargetEndpoint faça referência ao serviço de back-end pelo protocolo HTTPS e que você ativou o TLS:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

Se você estiver usando um TargetServer para definir o serviço de back-end, ative o TLS na definição do TargetServer:

<TargetServer name="target1">
  <Host>mocktarget.apigee.net</Host>
  <Port>443</Port>
  <IsEnabled>true</IsEnabled>
  <SSLInfo>
    <Enabled>true</Enabled>
  </SSLInfo> 
</TargetServer> 

No entanto, se você quiser que o Edge valide o certificado de back-end, crie um truststore que contenha o certificado ou a cadeia de certificados de back-end. Em seguida, especifique o truststore na definição de TargetEndpoint:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <TrustStore>ref://myTrustStoreRef</TrustStore>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

Ou na definição TargetServer:

<TargetServer name="target1">
  <Host>mockserver.apigee.net</Host>
  <Port>443</Port>
  <IsEnabled>true</IsEnabled>
  <SSLInfo>
    <Enabled>true</Enabled>
    <TrustStore>ref://myTrustStoreRef</TrustStore>
  </SSLInfo> 
</TargetServer>

Para configurar o TLS unidirecional:

  1. Se você quiser validar o certificado de back-end, crie um truststore no Edge e faça upload do certificado de back-end ou da cadeia de CAs, conforme descrito em Keystores e Truststores. Neste exemplo, se for necessário criar um truststore, nomeie-o como myTrustStore.
  2. Se você criou um truststore, use a seguinte chamada de API POST para criar a referência chamada myTrustStoreRef para o truststore criado acima:

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
      -d '<ResourceReference name="myTrustStoreRef">
        <Refers>myTrustKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
      </ResourceReference>' -u email:password
    
  3. Use a IU de gerenciamento de borda para atualizar a definição do TargetEndpoint para o proxy de API ou, se você definir o proxy de API em XML, edite os arquivos XML do proxy:
    1. Faça login na IU de gerenciamento do Edge em https://enterprise.apigee.com.
    2. No menu da interface do gerenciamento de borda, selecione APIs.
    3. Selecione o nome do proxy de API a ser atualizado.
    4. Selecione a guia Desenvolvimento.
    5. Em Pontos de extremidade de destino, selecione padrão.
    6. Na área de código, edite o elemento <HTTPTargetConnection> para adicionar o elemento <SSLInfo>. Especifique a referência correta do truststore e defina <Enabled> como verdadeiro:
      <TargetEndpoint name="default">
        …
        <HTTPTargetConnection>
          <SSLInfo>
            <Enabled>true</Enabled>
            <TrustStore>ref://myTrustStoreRef</TrustStore>
          </SSLInfo>
          <URL>https://myservice.com</URL>
        </HTTPTargetConnection>
        …
      </TargetEndpoint>
    7. Salve o proxy da API. Se o proxy de API foi implantado, salvá-lo novamente o implantará com a nova configuração.

Configurar o TLS bidirecional para o servidor de back-end

Se você quiser oferecer suporte a TLS bidirecional entre o Edge (cliente TLS) e o servidor de back-end (servidor TLS):

  • Crie um keystore no Edge e faça upload do certificado e da chave privada do Edge.
  • Se você quiser validar o certificado de back-end, crie um truststore no Edge que contenha o certificado e a cadeia de CA que você recebeu do servidor de back-end.
  • Atualize o TargetEndpoint de todos os proxies de API que fazem referência ao servidor de back-end para configurar o acesso TLS.

Como usar o alias da chave para especificar o certificado do keystore

É possível definir vários certificados, cada um com o próprio alias, no mesmo keystore. Por padrão, o Edge usa o primeiro certificado definido no keystore.

Também é possível configurar o Edge para usar o certificado especificado pela propriedade <KeyAlias>. Isso permite que você defina um único keystore para vários certificados e selecione o que quer usar na definição do TargetServer. Se o Edge não conseguir encontrar um certificado com um alias que corresponda a <KeyAlias>, ele usará a ação padrão de selecionar o primeiro certificado no keystore.

Os usuários do Edge para nuvem pública precisam entrar em contato com o suporte do Apigee Edge para ativar esse recurso.

Como configurar o TLS bidirecional

Para configurar o TLS bidirecional:

  1. Crie o keystore no Edge e faça upload do certificado e da chave privada usando o procedimento descrito aqui: Keystores e Truststores. Para este exemplo, crie um keystore chamado myTestKeystore que usa o nome de alias myKey para o certificado e a chave privada.
  2. Use a seguinte chamada de API POST para criar a referência chamada myKeyStoreRef para o keystore que você criou acima:

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
    -d '<ResourceReference name="myKeyStoreRef">
        <Refers>myTestKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
    </ResourceReference>' -u email:password
    

    A referência especifica o nome do keystore e o tipo de referência como KeyStore.

    Use a chamada GET API a seguir para visualizar a referência:

    curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/myKeyStoreRef /
    -u email:password
    
  3. Se você quiser validar o certificado de back-end, crie um truststore no Edge e faça upload do certificado e da cadeia de CA, conforme descrito aqui: Keystores e Truststores. Neste exemplo, se é necessário criar um truststore de myTrustStore.
  4. Se você criou um truststore, use a seguinte chamada de API POST para criar a referência chamada myTrustStoreRef para o truststore criado acima:

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
    -d '<ResourceReference name="myTrustStoreRef">
        <Refers>myTrustKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
    </ResourceReference>' -u email:password
    
  5. Use a IU de gerenciamento de borda para atualizar a definição do TargetEndpoint para o proxy de API ou, se você definir o proxy de API em XML, edite os arquivos XML do proxy:
    1. Faça login na IU de gerenciamento do Edge em https://enterprise.apigee.com.
    2. No menu da interface do gerenciamento de borda, selecione APIs.
    3. Selecione o nome do proxy de API a ser atualizado.
    4. Selecione a guia Desenvolvimento.
    5. Em Pontos de extremidade de destino, selecione padrão.
    6. Na área de código, edite o elemento <HTTPTargetConnection> para adicionar o elemento <SSLInfo>. Especifique o keystore e o alias de chave corretos e defina os elementos <Enabled> e <ClientAuthEnabled> como verdadeiros:
      <TargetEndpoint name="default">
        ...
        <HTTPTargetConnection>
          <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>true</ClientAuthEnabled>
            <KeyStore>ref://myKeyStoreRef</KeyStore>
            <KeyAlias>myKey</KeyAlias>
          </SSLInfo>
          <URL>https://myservice.com</URL>
        </HTTPTargetConnection>
        ...
      </TargetEndpoint>
    7. Salve o proxy da API. Se o proxy de API foi implantado, salvá-lo novamente o implantará com a nova configuração.

Para mais informações sobre as opções disponíveis no <TargetEndpoint>, incluindo o uso de variáveis para fornecer valores <SSLInfo> do TargetEndpoint, consulte a Referência de configuração do proxy de API.

Como ativar o SNI

O Edge permite o uso de indicação de nome do servidor (SNI, na sigla em inglês) de processadores de mensagens para segmentar endpoints no Apigee Edge para nuvem e para implantações de nuvem privada.

Para que o Edge da nuvem privada seja compatível com versões anteriores dos seus back-ends de destino, a Apigee desativou a SNI por padrão. Se o back-end de destino estiver configurado para oferecer suporte à SNI, você poderá ativar esse recurso. Consulte Como usar o SNI com o Edge para mais informações.