Como configurar hosts virtuais para a nuvem

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

• Sobre hosts virtuais
• Como configurar hosts virtuais
• Como configurar o TLS
• Keystores e Truststores

Quem pode criar e modificar hosts na nuvem

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 deve ter função de administrador da organização ou personalizado com permissões para modificar um host virtual. Os usuários em outras funções não têm autorização para criar hosts virtuais.

Por exemplo, os clientes pagantes podem:

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

Contas sem custo financeiro e de teste não podem criar ou modificar hosts virtuais e são limitadas a hosts virtuais criado para eles no momento do registro do Edge. Para mais informações sobre os planos de preços do Edge, acesse https://apigee.com/api-management/#/pricing.

Requisitos para configurar um host virtual para o Cloud

A tabela a seguir resume os requisitos para criar um host virtual:

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 crie um host virtual na interface do Edge.

Para criar um host virtual usando a interface 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 de um host virtual existente para editá-lo.
5. Consulte a tabela acima para informações detalhadas sobre como preencher os campos de 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 uma 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>

Nessa definição, você:

• Especifique o nome como myTLSVHost. Use o nome como referência o host virtual em um proxy de API ou em uma chamada de API.
• Especifique o alias do host como api.myCompany.com. Esta é a domínio público que seja usado para acessar suas APIs, conforme definido por uma definição de DNS e CNAME registro.
• Especifique o número da porta como 443. Se omitido, por padrão a porta está definida para 443.
• Ative o TLS conforme necessário.
  
  O elemento <Enable> é definida como verdadeira para ativar o TLS unidirecional, e os elementos e <KeyStore> especificam o keystore e o alias da chave usados pela conexão TLS.
  
  Para ativar o TLS bidirecional, defina <ClientAuthEnabled> como verdadeiro e especificar um truststore usando o elemento <TrustStore>. O truststore mantém o emissor do certificado do cliente e a cadeia de CA do certificado, que são obrigatórios.
  
  Observação:como o Edge era originalmente compatível com SSL, a tag que você usa para configurar O TLS é denominado <SSLInfo>.

Observe que há outras propriedades que podem ser definidas no host virtual. Para um para todas as propriedades, consulte Referência da propriedade de host virtual.

Decidir como especificar o nome do keystore e do truststore no host virtual

Ao configurar um host virtual para oferecer suporte a TLS, você especifica um keystore usando um referência. Uma referência é uma variável que contém o nome do keystore ou truststore, em vez de especificar o nome do keystore ou do truststore diretamente, conforme 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 dela para alterar o keystore usado pelo host virtual, geralmente porque o certificado no keystore atual é expira em breve. Alterar o valor da referência não exige que você reinicie o roteador de borda. Consulte Como trabalhar com referências para 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 no uso de referências a keystores e truststore

Você deve levar em consideração a seguinte restrição ao usar referências a keystores e truststores:

• Você só pode usar referências de keystore e truststore em hosts virtuais se oferecer suporte a SNI e você encerra o SSL nos roteadores da Apigee.
• Se você tiver um balanceador de carga na frente dos roteadores da Apigee e encerrar o TLS nos balanceador de carga, não será possível usar referências de keystore e truststore em hosts virtuais.

Definição de um host virtual para TLS bidirecional

Para ativar o TLS bidirecional, defina o elemento <ClientAuthEnabled> como true e especificar um truststore usando uma referência com o elemento <TrustStore>. O truststore mantém o emissor do certificado do cliente e a cadeia de CA do certificado, que são obrigatórios. 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 servidor host:

<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>

Nessa definição, você:

• Ative o TLS bidirecional definindo <ClientAuthEnabled> como verdadeiro.
• Especifique a referência ao truststore usando o elemento <TrustStore>. O truststore mantém o emissor do certificado do cliente e a cadeia de CA do certificado, que são obrigatórios.

Como definir um host virtual que usa 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.

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

Se você estiver executando TLS bidirecional, ainda precisará 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 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>

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 teste sem custo financeiro integrado. Ao criar o host virtual para usar o certificado e a chave sem custo financeiro da Apigee:

Como criar um host virtual

Use o procedimento a seguir 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 aponta para [org]-[environment].apigee.net.
2. Crie e configure um keystore, chamado myTestKeystore neste exemplo, fazendo o seguinte: usando o procedimento descrito aqui: Como criar keystores e truststore usando a interface do Edge. Para este exemplo, verificar se o keystore usa o nome de alias myKeyAlias para o certificado; chave privada.
3. Faça upload do certificado e da chave para o keystore. Verifique se o nome de domínio especificado pelo cert corresponde ao alias de host que você quer usar para o host virtual.

4. Crie uma referência para o keystore usando a interface ou a API Edge. A referência especifica o nome do keystore e o tipo de referência como KeyStore. Consulte Como trabalhar com referências para mais sobre como criar e modificar referências.

5. Crie o host virtual usando o botão Criar um Virtual Host (em inglês). Certifique-se de especificar a referência de keystore e o alias de chave corretos. Para usar a API, use a seguinte chamada de API POST para criar o keystore denominado 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 TLS bidirecional com o cliente, defina <ClientAuthEnabled> como verdadeiro e especificar o truststore usando o elemento <TrustStore>. O cliente precisa ser configurado corretamente para TLS bidirecional, o que significa que o Edge tem um truststore contendo o emissor e a cadeia de certificados do cliente. Criar o truststore usando o procedimento descrito aqui: Como criar keystores e truststore usando a interface do Edge

6. Se você já tiver proxies de API, adicione o host virtual ao elemento <HTTPConnection> no ProxyEndpoint. O host virtual é adicionado automaticamente a todos os novos proxies da API. Consulte 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 CNAME para o alias do host, acesse o proxy de API como 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

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

1. Modificar o valor de uma referência a um keystore ou um truststore.
   
   Observação: depois de definir um <KeyStore> ou <TrustStore> para usar uma referência, você pode alterar o valor da referência a qualquer momento. No entanto, se você quiser mudar <KeyStore> ou <TrustStore> para usar uma referência diferente ou mudar <KeyAlias> para usar um alias diferente, entre em contato com o suporte do Apigee Edge.
2. Modificar as propriedades TLS do host virtual.

A modificação do valor de um referência

É possível modificar o valor de uma referência para alterar o keystore ou o truststore usado por uma host.

Antes de modificar o valor da referência:

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 interface do Edge No novo keystore, Use o mesmo nome para o alias da chave que foi usado na chave atual Store.
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 interface do Edge
3. Modifique a referência conforme descrito em Como trabalhar com referências.

Modificar as propriedades TLS do host virtual

Clientes pagantes podem usar o Atualizar uma API Virtual Host para atualizar um host virtual. Essa API permite definir do host virtual descritas em Referência da propriedade de host virtual.

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

• O domínio especificado pelo alias de host não é usado em outra organização, e de nuvem.
• O nome de domínio é seu. Especificamente, o Edge verifica se as seguintes informações na "cert" corresponde 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 o comando Atualizar uma API Virtual Host Ao usar a API, você deve especificar a definição completa de o host virtual no corpo da solicitação, não somente os elementos que você quer alterar. Neste Por 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

A modificação de um host virtual para usar referências ao keystore e ao truststore

Todos os novos hosts virtuais do Edge in the Cloud usam referências 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.

Atualizar um host virtual para usar um referência

Use o procedimento a seguir 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 interface do Edge Se você já tem um o keystore, será possível 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á tem um truststore, você pode configurar uma referência para apontar para ele.
4. Crie uma nova referência para o truststore.
5. Atualizar o host virtual para definir o keystore, o alias, o truststore e qualquer outro TLS propriedades. 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 a Apigee Suporte para reiniciar os roteadores de borda para concluir o processo.