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

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

Pré-requisitos

  • Uma assinatura ativa do Azure. Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

  • 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 (herdado) O padrão é: <apim-service-name>.portal.azure-api.net
Portal do desenvolvedor O padrão é: <apim-service-name>.developer.azure-api.net
Gerenciamento O padrão é: <apim-service-name>.management.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).
  • 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.

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.

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é 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. Configurar domínio de gateway com certificado personalizado
  10. Selecione Adicionar ou selecione Atualizar para um ponto de extremidade existente.
  11. 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.

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

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.

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.

Próximas etapas

Atualizar e colocar em escala o serviço