Configurar um nome de domínio personalizado para sua instância de Gerenciamento de API do Azure

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

Quando você cria uma instância de serviço Gerenciamento de API do Azure na nuvem Azure, Azure atribui 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.

Important

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

Note

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

Important

Alterações na infraestrutura do serviço de Gerenciamento de API (como configurar domínios personalizados, adicionar certificados de AC, dimensionamento, configuração de rede virtual, alterações de zona de disponibilidade e adições de região) podem levar 15 minutos ou mais para serem concluídas, dependendo da camada de serviço e do tamanho da implantação. Espere tempos mais longos para uma instância com um número maior de unidades de escala ou configuração de várias regiões (gateways em vários locais). As alterações sem interrupção no Gerenciamento de API são executadas cuidadosamente para preservar a capacidade e a disponibilidade.

Enquanto o serviço está sendo atualizado, outras alterações de infraestrutura de serviço não podem ser feitas. No entanto, você pode definir APIs, produtos, políticas e configurações de usuário. O serviço não experimentará o tempo de inatividade do gateway e o Gerenciamento de API continuará a atender solicitações de API sem interrupção (exceto na camada Desenvolvedor).

Prerequisites

  • Uma instância de API Management. Para obter mais informações, consulte Criar uma instância de 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:

Endpoint Default
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 (todas as camadas, exceto Consumo) O padrão é: <apim-service-name>.developer.azure-api.net
Gerenciamento (somente camadas clássicas) O padrão é: <apim-service-name>.management.azure-api.net
API de configuração de gateway auto-gerenciado (v2) O padrão é: <apim-service-name>.configuration.azure-api.net
SCM (somente camadas de serviço clássicas) O padrão é: <apim-service-name>.scm.azure-api.net

Considerations

  • 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.
  • Ao configurar um domínio personalizado para o portal do Desenvolvedor, você pode habilitar o CORS para o novo nome de domínio. Isso é necessário para que os visitantes do portal do desenvolvedor usem o console interativo nas páginas de referência da API.

Opções de certificado de domínio

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

Warning

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.

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.

Definir um nome de domínio personalizado – portal

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

  1. Navegue até a instância de Gerenciamento de API no portal 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. Configurar domínio do gateway com certificado personalizado
  10. Selecione Adicionar ou selecione Atualizar para um ponto de extremidade existente.
  11. Clique em Salvar.

Configuração de DNS

Configure seu provedor DNS para mapear seu nome de domínio personalizado para o nome de domínio padrão da instância de Gerenciamento de API.

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, yourapim-service-name.azure-api.net). Um registro CNAME é mais estável do que um registro A caso o endereço IP seja alterado. Para obter mais informações, consulte Endereços IP do Gerenciamento de API do Azure e as Perguntas Frequentes do API Management.

Note

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.

Sincronização de certificados e solução de problemas para certificados com suporte Azure Key Vault

Quando você usa um certificado com suporte Azure Key Vault para um domínio personalizado, o Gerenciamento de API fornece controles e diagnósticos para ajudá-lo a manter os certificados sincronizados e resolver rapidamente os problemas de acesso.

Por exemplo, devido a uma alteração de configuração ou problema de conectividade, sua instância de Gerenciamento de API pode não conseguir buscar um certificado do nome do host no Azure Key Vault depois que um certificado é atualizado ou substituído lá. Quando isso acontece, sua instância de Gerenciamento de API continua a usar um certificado armazenado em cache até receber um certificado atualizado. Se o certificado armazenado em cache expirar, o tráfego de runtime para o gateway será bloqueado. Qualquer serviço upstream, como o Gateway de Aplicativo que usa a configuração de certificado do nome do host, também pode bloquear o tráfego de runtime do gateway quando um certificado armazenado em cache expirado é usado.

Use os controles e diagnósticos a seguir para manter seus certificados em sincronia e evitar ou minimizar o tempo de inatividade.

Sincronizar certificados

Selecione Sincronizar certificados na barra de comandos para iniciar manualmente a sincronização de certificados quando as impressões digitais do certificado forem alteradas. Essa opção permite que você evite aguardar o trabalho de sincronização automatizado, que normalmente é executado a cada 3 a 4 horas.

Screenshot do comando para sincronizar certificados de hostnames do Azure Key Vault no portal.

Exibir logs de sincronização

Selecione Exibir logs de sincronização na barra de comandos para abrir um painel com informações detalhadas de causa raiz quando a sincronização de certificados falhar. Esses logs ajudam você a diagnosticar e resolver problemas de sincronização mais rapidamente.

Restaurar o acesso ao cofre de chaves

O Gerenciamento de API mostra avisos proativos quando detecta problemas de acesso entre sua instância de Gerenciamento de API e o cofre de chaves usado pelo domínio personalizado. Esses problemas de acesso geralmente causam falhas de sincronização de certificado.

Se um aviso for exibido, selecione Restaurar para corrigir automaticamente o acesso com base no modelo de autorização do cofre de chaves. Dependendo do modelo, o Gerenciamento de API executa uma das seguintes ações para restaurar o acesso:

  • Atribui a função Key Vault Secrets User no cofre de chaves baseado em RBAC do Azure.
  • Concede a permissão GET para um cofre de chaves baseado em política de acesso.

Dicas adicionais de solução de problemas para falha na rotação de certificado do Azure Key Vault

  • Confirme se a identidade gerenciada usada para acessar o cofre de chaves existe.

  • Se a instância de Gerenciamento de API for implantada em uma rede virtual, confirme a conectividade de saída com a marca de serviço AzureKeyVault.

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

Limitações para nomes de domínios personalizados nas camadas v2

Atualmente, nas camadas Standard v2 e Premium v2, o API Management requer um nome DNS acessível publicamente para permitir o tráfego ao endpoint do Gateway. Se você configurar um nome de domínio personalizado para o ponto de extremidade do Gateway, esse nome deverá ser publicamente resolvível, não restrito a uma zona DNS privada.

Como uma solução alternativa em cenários em que você limita o acesso público ao gateway e configura um nome de domínio privado, é possível configurar o Gateway de Aplicativo para receber tráfego no nome de domínio privado e roteá-lo para o ponto de extremidade do Gateway da instância de Gerenciamento de API. Para obter uma arquitetura de exemplo, consulte este GitHub repositório.

Conteúdo relacionado

  • Last updated on