Configurar um nome de domínio personalizado para a sua instância de Azure API Management

APLICA-SE A: todas as camadas do Gerenciamento de API

Quando você cria uma instância de serviço do Gerenciamento de API na nuvem do Azure, o Azure atribui a ela um subdomínio azure-api.net (por exemplo, apim-service-name.azure-api.net). Também é possível pode expor os pontos de extremidade do Gerenciamento de API usando seu nome de domínio personalizado, como contoso.com . Este artigo mostra como mapear um nome DNS personalizado existente para pontos de extremidade expostos por uma instância do Gerenciamento de API.

Importante

O Gerenciamento de API aceita somente solicitações com valores de cabeçalho de host correspondentes:

• Ao nome de domínio padrão do gateway
• A qualquer um dos nomes de domínio personalizados configurados do gateway

Observação

Atualmente, não há suporte para nomes de domínio personalizados em um gateway de espaço de trabalho.

Pré-requisitos

• Uma instância de Gerenciamento de API. Para obter mais informações, consulte Criar uma instância do Gerenciamento de API do Azure.

• Um nome de domínio personalizado que pertence a você ou à sua organização. Este artigo não oferece instruções sobre como adquirir um nome de domínio personalizado.

• Opcionalmente, um certificado válido com chaves pública e privada (.PFX). A entidade ou o SAN (nome alternativo da entidade) precisa corresponder ao nome de domínio (isso permite que a instância do Gerenciamento de API exponha com segurança URLs via protocolo TLS).

  Confira Opções de certificado de domínio.

• Registros DNS hospedados em um servidor DNS para mapear o nome de domínio personalizado para o nome de domínio padrão da sua instância do Gerenciamento de API. Este tópico não oferece instruções sobre como hospedar os registros de DNS.

  Para saber mais sobre os registros necessários, confira Configuração de DNS posteriormente neste artigo.

Pontos de extremidade para domínios personalizados

Há vários pontos de extremidade do Gerenciamento de API para os quais você pode atribuir um nome de domínio personalizado. No momento, os seguintes pontos de extremidade estão disponíveis:

Ponto de extremidade	Padrão
Gateway	O padrão é: <apim-service-name>.azure-api.net. Gateway é o único ponto de extremidade disponível para configuração na camada de consumo. A configuração de ponto de extremidade de Gateway padrão permanece disponível depois que um domínio de Gateway personalizado é adicionado.
Portal do desenvolvedor	O padrão é: <apim-service-name>.developer.azure-api.net
Gerenciamento	O padrão é: <apim-service-name>.management.azure-api.net
API de Configuração (v2)	O padrão é: <apim-service-name>.configuration.azure-api.net
SCM	O padrão é: <apim-service-name>.scm.azure-api.net

Considerações

• Você pode atualizar qualquer um dos pontos de extremidade com suporte em sua camada de serviço. Tipicamente, os clientes atualizam o Gateway (essa URL é usada para chamar as APIs expostas por meio do Gerenciamento de API) e o Portal do desenvolvedor (a URL do portal do desenvolvedor).
• O ponto de extremidade do Gateway padrão permanece disponível depois que você configura um nome de domínio do Gateway e não pode ser excluído. Para outros pontos de extremidade do Gerenciamento de API (como o Portal do Desenvolvedor) que você configura com um nome de domínio personalizado, o ponto de extremidade padrão não está mais disponível.
• Somente os proprietários da instância do Gerenciamento de API podem usar os pontos de extremidade de Gerenciamento e SCM internamente. Com menos frequência, são atribuídos um nome de domínio personalizado a esses pontos de extremidade.
• As camadas Premium e do Desenvolvedor dão suporte à configuração de vários nomes de host para o ponto de extremidade do Gateway.
• Os nomes de domínio curinga, como *.contoso.com, têm suporte em todas as camadas, exceto a camada de Consumo. Um certificado de subdomínio específico (por exemplo, api.contoso.com) teria precedência sobre um certificado curinga (*.contoso.com) para solicitações a api.contoso.com.

Opções de certificado de domínio

O Gerenciamento de API dá suporte a certificados TLS personalizados ou certificados importados do Azure Key Vault. Você também pode habilitar um certificado gerenciado gratuito.

Aviso

Se você precisar de fixação de certificado, deverá usar um nome de domínio personalizado e um certificado personalizado ou Key Vault, não o certificado padrão nem o certificado gerenciado gratuito. Não é recomendável assumir uma dependência rígida de um certificado que você não gerencia.

Personalizado

Se você já tiver um certificado privado de um provedor de terceiros, poderá carregá-lo na instância do Gerenciamento de API. Ele precisa atender aos requisitos a seguir. (Se você habilitar o certificado gratuito gerenciado pelo Gerenciamento de API, ele já atenderá a esses requisitos.)

• Ser exportado como um arquivo PFX criptografado usando DES triplo e, opcionalmente, protegido por senha.
• Conter chave privada com pelo menos 2.048 bits de extensão
• Contém todos os certificados intermediários e o certificado raiz da cadeia de certificados.

Key Vault

É recomendável usar o Azure Key Vault para gerenciar certificados e configurá-los para autorenew.

Se você usar o Azure Key Vault para gerenciar um certificado TLS de domínio personalizado, verifique se o certificado foi inserido no Key Vault como certificado, não como segredo.

Cuidado

Ao usar um certificado do cofre de chaves no Gerenciamento de API, tenha cuidado para não excluir o certificado, o cofre de chaves ou a identidade gerenciada usados para acessar o cofre de chaves.

Para buscar um certificado TLS/SSL, o API Management deve ter a lista e obter permissões de segredos no Azure Key Vault que contém o certificado.

• Quando você usa o portal do Azure para importar o certificado, todas as etapas de configuração necessárias são concluídas automaticamente.

• Ao usar as ferramentas de linha de comando ou a API de gerenciamento, essas permissões precisam ser concedidas manualmente, em duas etapas:

  1. Na página de Identidades gerenciadas da instância do Gerenciamento de API, habilite uma identidade gerenciada atribuída pelo sistema ou pelo usuário. Anote a ID da entidade de segurança nessa página.
  2. Atribua permissões à identidade gerenciada para acessar o cofre de chaves. Use as etapas na seção a seguir.

  Configurar o acesso ao Key Vault

  1. No portal, navegue até o cofre de chaves.

  2. No menu à esquerda, selecione Configuração de acesso e anote o Modelo de permissão configurado.

  3. Dependendo do modelo de permissão, configure uma política de acesso do cofre de chaves ou o acesso do RBAC do Azure para uma identidade gerenciada do Gerenciamento de API.

     Para adicionar uma política de acesso do cofre de chaves:
     

     1. No menu à esquerda, selecione Políticas de acesso.
     2. Na página Políticas de acesso, selecione + Criar.
     3. Na guia Permissões, em Permissões em Permissões de segredo, escolha Obter e Listar. Clique em Avançar.
     4. Na guia Entidade de segurança, Selecionar entidade de segurança, procure o nome do recurso da identidade gerenciada e selecione Avançar. Se você estiver usando uma identidade atribuída pelo sistema, a entidade de segurança será o nome da instância de Gerenciamento de API.
     5. Selecione novamente Avançar. Na guia Revisar + criar, selecione Criar.

     Para configurar o acesso ao RBAC do Azure:
     

     1. No menu à esquerda, selecione Controle de acesso (IAM) .
     2. Na página Controle de acesso (IAM), selecione Adicionar atribuição de função.
     3. Na guia Função, selecione Usuário do Certificado do Key Vault.
     4. Na guia Membros, selecione Identidade gerenciada>+ Selecionar membros.
     5. Na página Selecionar identidade gerenciada, escolha a identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário associada à sua instância do Gerenciamento de API e clique em Selecionar.
     6. Selecione Examinar + atribuir.

Se o certificado estiver definido como autorenew e a camada do Gerenciamento de API tiver um SLA (ou seja, em todas as camadas, exceto a camada de Desenvolvedor), o Gerenciamento de API selecionará a versão mais recente automaticamente, sem nenhum tempo de inatividade para o serviço.

Para obter mais informações, confira Usar identidades gerenciadas no Gerenciamento de API do Azure.

Gerenciada

O Gerenciamento de API oferece um certificado TLS gerenciado e gratuito para seu domínio, caso você não queira comprar e gerenciar um certificado próprio. O certificado é renovado automaticamente.

Observação

O certificado TLS gerenciado gratuito está em versão prévia. Atualmente, ele não está disponível nas camadas de serviço v2.

Limitações

• Atualmente, ele pode ser usado somente com o ponto de extremidade do gateway do serviço de Gerenciamento de API
• Sem suporte com o gateway auto-hospedado
• Sem suporte nas seguintes regiões do Azure: Sul da França e Oeste da África do Sul
• Atualmente disponível apenas na nuvem do Azure
• Não dá suporte a nomes de domínio raiz (por exemplo, contoso.com). Exige um nome totalmente qualificado, como api.contoso.com.
• Só dá suporte a nomes de domínio público
• Só pode ser configurado ao atualizar uma instância de Gerenciamento de API existente e não ao criar uma instância

Definir um nome de domínio personalizado – portal

Escolha as etapas de acordo com o certificado de domínio que você deseja usar.

Personalizado

1. Navegue até sua instância de API Management no portal do Azure.
2. Na navegação à esquerda, selecione Domínios personalizados.
3. Selecione + Adicionarou selecione um ponto de extremidade existente que você deseja atualizar.
4. Na janela à direita, selecione o tipo do ponto de extremidade para o domínio personalizado.
5. No campo Nome do host, especifique o nome você deseja usar. Por exemplo, api.contoso.com.
6. Em Certificado, selecione Personalizado
7. Selecione o campo Arquivo de certificado para selecionar e carregar um certificado.
8. Carregue um arquivo .PFX válido e forneça a senha, se o certificado estiver protegido por uma senha.
9. Ao configurar um ponto de extremidade do Gateway, selecione ou desmarque outras opções conforme necessário, incluindo Negociar certificado de cliente ou Associação SSL padrão.
10. Selecione Adicionar ou selecione Atualizar para um ponto de extremidade existente.
11. Clique em Salvar.

Key Vault

1. Navegue até sua instância de API Management no portal do Azure.
2. Na navegação à esquerda, selecione Domínios personalizados.
3. Selecione + Adicionarou selecione um ponto de extremidade existente que você deseja atualizar.
4. Na janela à direita, selecione o tipo do ponto de extremidade para o domínio personalizado.
5. No campo Nome do host, especifique o nome você deseja usar. Por exemplo, api.contoso.com.
6. Em Certificado, selecione Key Vault e Selecionar.
   1. Selecione Assinatura na lista suspensa.
   2. Selecione Key Vault na lista suspensa.
   3. Depois que os certificados tiverem sido carregados, selecione o Certificado na lista suspensa. Clique em Selecionar.
   4. Em Identidade do cliente, selecione uma identidade atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário habilitada na instância para acessar o cofre de chaves.
7. Ao configurar um ponto de extremidade do Gateway, selecione ou desmarque outras opções conforme necessário, incluindo Negociar certificado de cliente ou Associação SSL padrão.
8. Selecione Adicionar ou selecione Atualizar para um ponto de extremidade existente.
9. Clique em Salvar.

Gerenciada

1. Navegue até sua instância de API Management no portal do Azure.
2. Na navegação à esquerda, selecione Domínios personalizados.
3. Selecione + Adicionarou selecione um ponto de extremidade existente que você deseja atualizar.
4. Na janela à direita, selecione o tipo do ponto de extremidade para o domínio personalizado.
5. No campo Nome do host, especifique o nome você deseja usar. Por exemplo, api.contoso.com.
6. Em Certificado, selecione Gerenciado para habilitar um certificado gratuito gerenciado pelo Gerenciamento de API. O certificado gerenciado está disponível em versão prévia apenas para o ponto de extremidade do Gateway.
7. Copie os seguintes valores e use-os para configurar o DNS:
   • Registro TXT
   • Registro CNAME
8. Ao configurar um ponto de extremidade do Gateway, selecione ou desmarque outras opções conforme necessário, incluindo Negociar certificado de cliente ou Associação SSL padrão.
9. Selecione Adicionar ou selecione Atualizar para um ponto de extremidade existente.
10. Clique em Salvar.

Observação

O processo de atribuição do certificado pode levar aproximadamente 15 minutos dependendo do tamanho da implantação. A camada de Desenvolvedor tem tempo de inatividade, já as camadas Básica e superiores não têm.

Configuração de DNS

• Configure um registro CNAME para seu domínio personalizado.
• Ao usar o certificado gerenciado gratuito do Gerenciamento de API, configure também um registro TXT para estabelecer sua propriedade do domínio.

Observação

O certificado gratuito é emitido pela DigiCert. Para alguns domínios, é necessário permitir explicitamente a DigiCert como um emissor do certificado criando um registro de domínio CAA com o valor 0 issue digicert.com.

Registro CNAME

Configure um registro CNAME que aponta do nome de domínio personalizado (por exemplo, api.contoso.com) para o nome do host do serviço de Gerenciamento de API (por exemplo, <apim-service-name>.azure-api.net). Um registro CNAME é mais estável do que um registro A no caso de alterações de endereço IP. Para obter mais informações, confira endereços IP do Gerenciamento de API do Azure e Perguntas frequentes do Gerenciamento de API.

Observação

Alguns registradores de domínio só permitem mapear subdomínios ao usar um registro CNAME, como www.contoso.com, e não nomes de raiz, como contoso.com. Para obter mais informações sobre os registros CNAME, consulte a documentação fornecida por seu registrador ou Nomes de Domínio IETF - Implementação e Especificação.

Cuidado

Ao usar o certificado gerenciado gratuito e configurar um registro CNAME junto ao seu provedor de DNS, certifique-se de que ele seja resolvido para o nome do host padrão do serviço de Gerenciamento de API (<apim-service-name>.azure-api.net). Atualmente, o Gerenciamento de API não renovará o certificado automaticamente se o registro CNAME não resolver para o nome do host padrão do Gerenciamento de API. Por exemplo, se estiver usando o certificado gerenciado gratuito e usar a Cloudflare como seu provedor de DNS, certifique-se de que o proxy de DNS não esteja habilitado no registro CNAME.

Registro TXT

Ao habilitar o certificado gerenciado gratuito para o Gerenciamento de API, configure também um registro TXT em sua zona DNS para estabelecer sua propriedade do nome de domínio.

• O nome do registro é seu nome de domínio personalizado prefixado por apimuid. Exemplo: apimuid.api.contoso.com.
• O valor é um identificador de propriedade de domínio fornecido pela instância do Gerenciamento de API.

Quando você usa o portal para configurar o certificado gerenciado gratuito para seu domínio personalizado, o nome e o valor do registro TXT necessário são exibidos automaticamente.

Você também pode obter um identificador de propriedade de domínio chamando a API REST Obter Identificador de Propriedade de Domínio.

Como o servidor proxy do Gerenciamento de API responde a certificados SSL no handshake de TLS

Ao configurar um domínio personalizado para o ponto de extremidade do gateway, você pode definir propriedades adicionais que determinam como o Gerenciamento de API responde com um certificado do servidor, dependendo da solicitação do cliente.

Clientes chamando com o cabeçalho da SNI (Indicação de Nome de Servidor)

Se você tiver um ou vários domínios personalizados configurados para o ponto de extremidade de gateway, o Gerenciamento de API poderá responder a solicitações HTTPS de um dos seguintes:

• Domínio personalizado (por exemplo, contoso.com)
• Domínio padrão (por exemplo, apim-service-name.azure-api.net).

Com base nas informações no cabeçalho da SNI, o Gerenciamento de API responde com o certificado do servidor apropriado.

Clientes chamando sem cabeçalho de SNI

Se você estiver usando um cliente que não envia o cabeçalho de SNI, o Gerenciamento de API criará respostas com base na seguinte lógica:

• Se o serviço tem apenas um domínio personalizado configurado para o gateway, o certificado padrão é o certificado emitido para o domínio personalizado do gateway.

• Se o serviço tiver vários domínios personalizados configurados para o gateway (com suporte nas camadas Desenvolvedor e Premium), você poderá designar o certificado padrão definindo a propriedade defaultSslBinding como true ("defaultSslBinding":"true"). No portal, marque a caixa de seleção Associação SSL padrão.

  Se você não definir a propriedade, o certificado padrão será o certificado emitido para o domínio de gateway padrão hospedado em *.azure-api.net.

Suporte para a solicitação PUT/POST com grande payload

O servidor proxy do Gerenciamento de API dá suporte a solicitações com grandes conteúdos (> 40 KB) ao usar certificados no lado do cliente em HTTPS. Para impedir que a solicitação do servidor congele, você pode definir a propriedade negotiateClientCertificate para true ("negotiateClientCertificate": "true") no nome do host do gateway. No portal, marque a caixa de seleção Negociar certificado do cliente.

Se a propriedade for definida como true, o certificado do cliente é solicitado ao tempo de conexão SSL/TLS, antes de qualquer troca de solicitação HTTP. Uma vez que a configuração se aplica ao nível do Nome do host do gateway, todas as solicitações de conexão solicitam o certificado do cliente. Você pode contornar essa limitação e configurar até 20 domínios personalizados para o gateway (com suporte apenas na camada Premium).

Próximas etapas

Atualizar e colocar em escala o serviço