Como configurar hosts virtuais para a nuvem

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

Um cliente do Cloud com uma conta paga pode criar um host virtual em uma organização.

Saiba mais:

Quem pode criar e modificar hosts virtuais no Cloud

A criação e a modificação de hosts virtuais estão disponíveis apenas para contas pagas no Edge Cloud. O usuário que cria o host virtual precisa ter o papel de administrador da organização ou um papel personalizado com permissões para modificar um host virtual. Os usuários em outros papéis não têm autorização para criar hosts virtuais.

Por exemplo, os clientes podem fazer o seguinte:

  • Ativar TLS unidirecional e bidirecional
  • Especificar o keystore/truststore usado pelo host virtual

As contas sem custo financeiro e de teste não podem criar nem modificar hosts virtuais e são limitadas aos hosts virtuais criados para elas no momento do registro do Edge. Para mais informações sobre os planos de preços do Edge, consulte https://apigee.com/api-management/#/pricing.

Requisitos para configurar um host virtual para o Cloud

A tabela a seguir resume os requisitos para a criação de um host virtual:

Categorias Requisito Descrição
Tipo de conta Pago Contas sem custo financeiro e de teste não podem criar nem modificar hosts virtuais.
Função do usuário administrador da organização Somente um administrador da organização pode criar um host virtual ou um usuário em um papel personalizado com permissões para modificar um host virtual.
Número de hosts virtuais Máximo de 20

Há um limite de 20 hosts virtuais por organização/ambiente no Cloud.

Observação: não há limite para o número de hosts virtuais na nuvem privada.

A maioria das organizações/ambientes usa dois hosts virtuais: um para HTTP e outro para acesso HTTPS. Talvez você precise de hosts virtuais adicionais se a organização/o ambiente permitir o acesso usando nomes de domínio diferentes.

URL de base Inclui o protocolo Ao definir o URL base para o host virtual na interface ou na API, você precisa especificar o protocolo (ou seja, "http://" ou "https://") como parte do URL.
Porta 443

Só é possível criar um host virtual na porta 443.

Observe que é possível criar vários hosts virtuais na porta 443, desde que eles tenham aliases de host exclusivos e todos ofereçam suporte a TLS.

TLS Obrigatório

Só é possível criar um host virtual compatível com TLS sobre HTTPS. É preciso já ter criado um keystore e, opcionalmente, um truststore, contendo o certificado e a chave TLS.

Você precisa ter um certificado assinado por uma entidade confiável, como a CSI ou a VeriSign. Não é possível usar um certificado autoassinado.

Se você precisar de acesso HTTP, entre em contato com o suporte do Apigee Edge.

Protocolo TLS TLS 1.2

O Edge no Cloud só oferece suporte à versão 1.2 do TLS.

Alias de host Exclusivo na organização e no ambiente O alias do host não existe para outra combinação de organização/ambiente.
Nome de domínio Pertence ao cliente

Você precisa ser o proprietário do nome de domínio especificado no host virtual. Verifica se o nome de domínio, conforme definido pelo alias do host, corresponde aos metadados no certificado TLS.

Especificamente, o Edge verifica as seguintes informações no certificado:

  • CN - Nome comum
  • SAN: nome alternativo do assunto

Caracteres curinga são permitidos no SAN ou na CN, por exemplo, *.myco.net.

O Edge também valida que o certificado não expirou.

Suporte a SNI de app cliente Todos os apps clientes que acessam o host virtual precisam oferecer suporte à SNI.

O suporte a SNI é obrigatório para todos os aplicativos.

Criar um host virtual usando um navegador

A maioria dos exemplos nesta seção usa a API Edge para criar ou modificar hosts virtuais, mas é possível criar um host virtual na IU do Edge.

Para criar um host virtual usando a IU do Edge:

  1. Faça login em apigee.com/edge.
  2. Selecione Administrador > Hosts virtuais.
  3. Selecione o ambiente, como prod ou test.
  4. Selecione + Virtual Host para criar um host virtual ou selecione o nome de um host virtual existente para editá-lo.
  5. Consulte a tabela acima para informações detalhadas sobre como preencher os campos do host virtual.

Como definir um host virtual para TLS unidirecional

Um objeto XML que define o host virtual. Por exemplo, o objeto XML a seguir define um host virtual para TLS unidirecional:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>api.myCompany.com</HostAlias> 
    </HostAliases> 
    <Port>443</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

Nesta definição, você:

  • Especifique o name como myTLSVHost. Use o nome para fazer referência ao host virtual em um proxy de API ou em uma chamada de API.
  • Especifique o alias do host como api.myCompany.com. Esse é o domínio público usado para acessar suas APIs, conforme definido por uma definição de DNS e por um registro CNAME.
  • Especifique o número da porta como 443. Se omitido, por padrão, a porta será definida como 443.
  • Ative o TLS conforme necessário.

    O elemento <Enable> é definido como verdadeiro para ativar o TLS unidirecional, e os elementos <KeyStore> especificam o keystore e o alias da chave usados pela conexão TLS.

    Para ativar o TLS bidirecional, defina <ClientAuthEnabled> como verdadeiro e especifique um truststore usando o elemento <TrustStore>. O truststore contém o emissor do certificado do cliente e a cadeia de CA do certificado, que é necessária.

    Observação:como o Edge era compatível com SSL, a tag que você usa para configurar o TLS é chamada de <SSLInfo>.

Há outras propriedades que podem ser definidas no host virtual. Para conferir uma referência para todas as propriedades, consulte Referência de propriedades do host virtual.

Como decidir como especificar o nome do keystore e do truststore no host virtual

Ao configurar um host virtual para oferecer suporte a TLS, especifique um keystore usando uma referência. Uma referência é uma variável que contém o nome do keystore ou do truststore, em vez de especificar o nome do keystore ou do truststore diretamente, como mostrado abaixo:

    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>

A vantagem de usar uma referência é que você pode alterar o valor da referência para alterar o keystore usado pelo host virtual, geralmente porque o certificado no keystore atual vai expirar em um futuro próximo. Alterar o valor da referência não exige que você reinicie o roteador de borda. Consulte Como trabalhar com referências para saber mais sobre como criar e modificar referências.

Só é possível usar uma referência ao keystore e truststore. Não é possível usar uma referência ao alias. Ao alterar a referência para um keystore, verifique se o nome do alias do certificado é o mesmo do keystore antigo.

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

Considere a seguinte restrição ao usar referências a keystores e truststores:

  • Só é possível usar referências de keystore e truststore em hosts virtuais se você oferecer suporte à SNI e encerrar o SSL 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 as referências de keystore e truststore em hosts virtuais.

Como definir um host virtual para TLS bidirecional

Para ativar o TLS bidirecional, defina o elemento <ClientAuthEnabled> como true e especifique um truststore usando uma referência com o elemento <TrustStore>. O truststore contém o emissor do certificado do cliente e a cadeia de CA do certificado, que é necessária. O cliente também precisa ser configurado corretamente para TLS bidirecional.

Para criar um host virtual para TLS bidirecional, crie um objeto XML que defina o host virtual:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>api.myCompany.com</HostAlias> 
    </HostAliases> 
    <Port>443</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://myTestTruststoreRef</TrustStore> 
    </SSLInfo>
</VirtualHost>

Nesta definição, você:

  • Para ativar o TLS bidirecional, defina <ClientAuthEnabled> como verdadeiro.
  • Especifique a referência ao truststore usando o elemento <TrustStore>. O truststore contém o emissor do certificado do cliente e a cadeia de CA do certificado, que é necessária.

Como definir um host virtual que usa o certificado e a chave de avaliação sem custo financeiro da Apigee

Se você tiver uma conta paga do Edge para o Cloud e ainda não tiver um certificado e uma chave TLS, crie um host virtual que usa 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.

O certificado de avaliação sem custo financeiro da Apigee está definido para um domínio de *.apigee.net. Portanto, o <HostAlias> do host virtual também precisa estar no formato *.apigee.net.

Se você estiver executando o TLS bidirecional, ainda será preciso definir o elemento <ClientAuthEnabled> como true e especificar um truststore usando uma referência com o elemento <TrustStore>, conforme descrito acima em Como definir um host virtual para TLS bidirecional.

Um objeto XML que define o host virtual usando a chave e o certificado de avaliação 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>

O valor padrão do elemento <UseBuiltInFreeTrialCert> é falso.

Para TLS bidirecional, defina o host virtual como:

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

Na interface do Edge, selecione a opção Usar certificado de avaliação sem custo financeiro integrado ao criar o host virtual para usar o certificado e a chave sem custo financeiro da Apigee:

Selecione &quot;Usar certificado de teste sem custo financeiro integrado&quot;

Como criar um host virtual

Siga o procedimento abaixo para criar o host virtual:

  1. Crie uma entrada DNS e um registro CNAME para seu domínio público, api.myCompany.com para este exemplo, que aponte para [org]-[environment].apigee.net.
  2. Crie e configure um keystore chamado myTestKeystore neste exemplo, usando o procedimento descrito aqui: Como criar keystores e truststore usando a IU do Edge. Neste exemplo, verifique se o keystore usa um nome de alias myKeyAlias para o certificado e a chave privada.
  3. Faça upload do certificado e da chave para o keystore. Verifique se o nome de domínio especificado pelo certificado corresponde ao alias de host a ser usado para o host virtual.
  4. Crie uma referência ao keystore usando a API ou a interface do Edge. A referência especifica o nome do keystore e o tipo de referência como KeyStore. Consulte Como trabalhar com referências para saber mais sobre como criar e modificar referências.

  5. Crie o host virtual usando a API Create a Virtual Host. Certifique-se de especificar a referência de keystore e o alias da chave corretos. Para usar a API, use a seguinte chamada de API POST para criar o keystore chamado myTLSVHost:
    curl -X POST -H "Content-Type:application/xml" \
      https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts \
      -d '<VirtualHost name="myTLSVHost">
        <HostAliases>
          <HostAlias>api.myCompany.com</HostAlias>
        </HostAliases>
        <Port>443</Port>
        <SSLInfo>
          <Enabled>true</Enabled>
          <ClientAuthEnabled>false</ClientAuthEnabled>
          <KeyStore>ref://myTestKeystoreRef</KeyStore>
          <KeyAlias>myKeyAlias</KeyAlias>
        </SSLInfo>
      </VirtualHost>' \
      -u orgAdminEmail:password

    Se você estiver executando o TLS bidirecional com o cliente, defina <ClientAuthEnabled> como verdadeiro e especifique o truststore usando o elemento <TrustStore>. O cliente precisa ser configurado corretamente para o TLS bidirecional, o que significa que o Edge tem um truststore que contém o emissor do certificado e a cadeia de certificados do cliente. Crie o truststore usando o procedimento descrito aqui: Como criar keystores e truststore usando a IU do Edge.

  6. Se você tiver proxies de API, adicione o host virtual ao elemento <HTTPConnection> no ProxyEndpoint. O host virtual é adicionado automaticamente a todos os novos proxies de API. Consulte Como configurar um proxy de API para usar um host virtual.

Depois de atualizar um proxy de API para usar o host virtual e criar a entrada DNS e o registro CNAME para o alias do host, você pode acessar o proxy de API conforme mostrado abaixo:

https://api.myCompany.com/v1/{project-base-path}/{resource-path}

Exemplo:

https://api.myCompany.com/v1/weather/forecastrss?w=12797282

Como modificar um host virtual

Existem duas tarefas principais que os clientes pagos do Cloud realizam para modificar um host virtual:

  1. Modificar o valor de uma referência a um keystore ou truststore.

    Observação: depois de definir um <KeyStore> ou <TrustStore> para usar uma referência, é possível alterar o valor da referência a qualquer momento. No entanto, se você quiser alterar <KeyStore> ou <TrustStore> para usar uma referência diferente ou alterar <KeyAlias> para usar um alias diferente, será necessário entrar em contato com o suporte do Apigee Edge.
  2. Modificar as propriedades TLS do host virtual.

Modificar o valor de uma referência

Você pode modificar o valor de uma referência para alterar o keystore ou o truststore usado por um host virtual.

Antes de modificar o valor da referência, faça o seguinte:

  1. Crie um novo keystore e faça upload de um certificado e uma chave, conforme descrito em Como criar keystores e truststore usando a IU do Edge. No novo keystore, verifique se você está usando o mesmo nome para o alias de chave usado no armazenamento de chave atual.
  2. Se necessário, crie um novo truststore e faça upload de um certificado, conforme descrito em Como criar keystores e truststore usando a IU do Edge.
  3. Modifique a referência conforme descrito em Como trabalhar com referências.

Modificar as propriedades TLS do host virtual

Clientes pagos podem usar a API Update a Virtual Host para atualizar um host virtual. Essa API permite definir todas as propriedades do host virtual descritas em Referência da propriedade do host virtual.

Quando você modifica o host virtual, o Edge executa uma validação semelhante a quando você cria um host virtual. Ou seja, em uma modificação, o Edge valida que:

  • O domínio especificado pelo alias do host não é usado em outra organização e em outro ambiente.
  • O nome de domínio é seu. Especificamente, o Edge verifica se as seguintes informações no certificado correspondem ao alias do host:
    • CN - Nome comum
    • SAN: nome alternativo do assunto
    • O Edge valida que o certificado não expirou.

Para modificar um host virtual usando a API Edge, faça o seguinte:

  1. Atualize o host virtual usando a API Update a Virtual Host. Ao usar a API, especifique a definição completa do host virtual no corpo da solicitação, não apenas os elementos que você quer mudar. Neste exemplo, você define o valor da propriedade proxy_read_timeout:

    curl -X PUT -H "Content-Type:application/xml" \
      https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
      -d '<VirtualHost name="myTLSVHost">
        <HostAliases>
          <HostAlias>api.myCompany.com</HostAlias>
        </HostAliases>
        <Port>443</Port>
        <SSLInfo>
          <Enabled>true</Enabled>
          <ClientAuthEnabled>false</ClientAuthEnabled>
          <KeyStore>ref://myTestKeystoreRef</KeyStore>
          <KeyAlias>myKeyAlias</KeyAlias>
        </SSLInfo>
        <Properties>
           <Property name="proxy_read_timeout">50</Property>
             </Properties>
      </VirtualHost>' \
      -u orgAdminEmail:password

Como modificar um host virtual para usar referências ao keystore e ao truststore

Todos os novos hosts virtuais do Edge no Cloud usam referência ao keystore e ao truststore. As referências permitem alterar o keystore e o truststore sem entrar em contato com o suporte do Apigee Edge.

Hosts virtuais mais antigos no Apigee Edge podem não estar configurados para usar referências para keystores e truststores. Nesse caso, é possível atualizar o host virtual para usar uma referência.

Como atualizar um host virtual para usar uma referência

Use o procedimento abaixo para atualizar o host virtual:

  1. Se necessário, crie um novo keystore e faça upload de um certificado, conforme descrito em Como criar keystores e truststore usando a IU do Edge. Se você já tiver um keystore, poderá configurar uma referência para apontar para ele.
  2. Crie uma nova referência ao keystore.
  3. Se necessário, crie um novo truststore e faça upload de um certificado. Se você já tiver um truststore, poderá configurar uma referência para apontar para ele.
  4. Crie uma nova referência ao truststore.
  5. Atualize o host virtual para definir o keystore, o alias, o truststore e outras propriedades do TLS. O payload da chamada é:
    curl -X PUT -H "Content-Type:application/xml" \
      https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
      -d '<VirtualHost  name="myTLSVHost">
            <HostAliases>
              <HostAlias>api.myCompany.com</HostAlias>
            </HostAliases>
            <Port>443</Port>
            <OCSPStapling>off</OCSPStapling>
            <SSLInfo>
              <Enabled>true</Enabled>
              <ClientAuthEnabled>true</ClientAuthEnabled>
              <KeyStore>ref://myKeyStore2Way</KeyStore>
              <KeyAlias>keyAlias</KeyAlias>
              <TrustStore>ref://myTrustStore2Way</TrustStore>
              <IgnoreValidationErrors>false</IgnoreValidationErrors>
            </SSLInfo>
          </VirtualHost>' \
        -u orgAdminEmail:pWord
  6. Entre em contato com o suporte da Apigee para reiniciar os roteadores de borda e concluir o processo.