Configurar um nome de domínio personalizado para a sua instância da Gestão de API do Azure

APLICA-SE A: Todas as camadas de gerenciamento de API

Quando cria uma instância de serviço de Gestão de API do Azure na nuvem do Azure, o Azure atribui-lhe um azure-api.net subdomínio (por exemplo, apim-service-name.azure-api.net). Você também pode expor seus pontos de extremidade de Gerenciamento de API usando seu próprio 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 de Gerenciamento de API.

Importante

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

• O nome de domínio padrão do gateway
• Qualquer um dos nomes de domínio personalizados configurados do Gateway

Pré-requisitos

• Uma instância de gerenciamento de API. 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 si ou à sua organização. Este artigo não fornece instruções sobre como obter um nome de domínio personalizado.

• Opcionalmente, um certificado válido com uma chave pública e privada (. PFX). O assunto ou o nome alternativo do assunto (SAN) deve corresponder ao nome de domínio (isso permite que a instância de Gerenciamento de API exponha URLs com segurança por TLS).

  Consulte 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 de Gerenciamento de API. Este tópico não fornece instruções sobre como hospedar os registros DNS.

  Para obter mais informações sobre os registros necessários, consulte Configuração de DNS, mais adiante neste artigo.

Pontos de extremidade para domínios personalizados

Há vários pontos de extremidade de Gerenciamento de API aos quais você pode atribuir um nome de domínio personalizado. Atualmente, os seguintes pontos de avaliação estão disponíveis:

Ponto final	Predefinido
Gateway	O padrão é: <apim-service-name>.azure-api.net. O gateway é o único ponto de extremidade disponível para configuração na camada de Consumo. A configuração padrão do ponto de extremidade do Gateway permanece disponível depois que um domínio de Gateway personalizado é adicionado.
Portal do programador	O padrão é: <apim-service-name>.developer.azure-api.net
Gestão	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

• Pode atualizar qualquer um dos endpoints suportados no seu escalão de serviço. Normalmente, os clientes atualizam o Gateway (este URL é utilizado para chamar as APIs expostas através da Gestão de API) e o Portal do programador (o URL do portal do programador).
• O ponto de extremidade padrão do Gateway permanece disponível após a configuração de um nome de domínio personalizado do Gateway e não pode ser excluído. Para outros pontos de extremidade de 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.
• Apenas os proprietários da instância da Gestão de API podem utilizar os endpoints Gestão e SCM internamente. São atribuídos com menos frequência um nome de domínio personalizado a estes endpoints.
• Os escalões Premium e Programador suportam a definição de vários nomes de anfitrião para o ponto final do Gateway.
• Nomes de domínio curinga, como *.contoso.com, são suportados em todas as camadas, exceto na camada 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 de api.contoso.com.

Opções de certificado de domínio

A Gestão de API suporta certificados TLS personalizados ou certificados importados do Azure Key Vault. Também pode ativar um certificado gerido gratuito.

Aviso

Se você precisar de fixação de certificado, use um nome de domínio personalizado e um certificado personalizado ou do Cofre da Chave, não o certificado padrão ou o certificado gerenciado gratuito. Não recomendamos que assuma uma dependência rígida de um certificado que não é gerido por si.

Personalizadas

Se você já tiver um certificado privado de um provedor de terceiros, poderá carregá-lo em sua instância de Gerenciamento de API. Deve satisfazer os seguintes requisitos: (Se você habilitar o certificado gratuito gerenciado pelo Gerenciamento de API, ele já atende a esses requisitos.)

• Exportado como ficheiro PFX, encriptado com DES triplo e, opcionalmente, protegido por palavra-passe.
• Contém chave privada com pelo menos 2.048 bits de comprimento
• Conter todos os certificados intermédios e o certificado de raiz na cadeia de certificados.

Key Vault

Recomendamos usar o Azure Key Vault para gerenciar seus certificados e defini-los como autorenew.

Se você usar o Cofre da Chave do Azure para gerenciar um certificado TLS de domínio personalizado, verifique se o certificado é inserido no Cofre da Chave como um certificado, não como um segredo.

Atenção

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

Para obter um certificado TLS/SSL, o Gerenciamento de API deve ter a lista e obter permissões de segredos no Cofre da Chave do Azure 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.

• Quando você usa ferramentas de linha de comando ou API de gerenciamento, essas permissões devem ser concedidas manualmente, em duas etapas:

  1. Na página Identidades gerenciadas da sua instância de Gerenciamento de API, habilite uma identidade gerenciada atribuída pelo sistema ou pelo usuário. Anote o ID principal 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 cofre de chaves

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

  2. No menu à esquerda, selecione Configuração do Access e anote o modelo de permissão que está configurado.

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

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

     1. No menu à esquerda, selecione Políticas de acesso.
     2. Na página Políticas de acesso , selecione + Criar.
     3. No separador Permissões, em Permissões secretas, selecione Obter e Listar e, em seguida, selecione Seguinte.
     4. No separador Principal, Selecione entidade de segurança, procure o nome do recurso da sua identidade gerida e, em seguida, selecione Seguinte. Se você estiver usando uma identidade atribuída ao sistema, o principal será o nome da sua instância de Gerenciamento de API.
     5. Selecione Avançar novamente. No separador Rever + criar, selecione Criar.

     Para configurar o acesso ao Azure RBAC:
     

     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 de Segredos do Cofre da Chave.
     4. Na guia Membros, selecione Identidade> gerenciada+ Selecionar membros.
     5. Na página Selecionar identidade gerenciada, selecione a identidade gerenciada atribuída ao sistema ou uma identidade gerenciada atribuída pelo usuário associada à sua instância de Gerenciamento de API e selecione Selecionar.
     6. Selecione Rever + atribuir.

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

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

Geridas

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

Nota

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

Limitações

• Atualmente, só pode ser usado com o ponto de extremidade Gateway do seu serviço de Gerenciamento de API
• Não suportado com o gateway auto-hospedado
• Sem suporte nas seguintes regiões do Azure: França Sul e África do Sul Oeste
• Atualmente disponível apenas na nuvem do Azure
• Não suporta nomes de domínio raiz (por exemplo, contoso.com). Requer um nome totalmente qualificado, como api.contoso.com.
• Suporta apenas nomes de domínio público
• Só pode ser configurado ao atualizar uma instância de Gerenciamento de API existente, 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 deseja usar.

Personalizadas

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

Key Vault

1. Navegue até sua instância de Gerenciamento de API no portal do Azure.
2. Na navegação à esquerda, selecione Domínios personalizados.
3. Selecione +Adicionar ou selecione um ponto de extremidade existente que você deseja atualizar.
4. Na janela à direita, selecione o Tipo de ponto de extremidade para o domínio personalizado.
5. No campo Nome do host , especifique o nome que deseja usar. Por exemplo, api.contoso.com.
6. Em Certificado, selecione Cofre da Chave e, em seguida, Selecionar.
   1. Selecione a Assinatura na lista suspensa.
   2. Selecione o Cofre da chave na lista suspensa.
   3. Depois que os certificados forem 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 de gateway, selecione ou desmarque outras opções conforme necessário, incluindo Negociar certificado de cliente ou Vinculação SSL padrão.
8. Selecione Adicionar ou selecione Atualizar para um ponto de extremidade existente.
9. Selecione Guardar.

Geridas

1. Navegue até sua instância de Gerenciamento de API no portal do Azure.
2. Na navegação à esquerda, selecione Domínios personalizados.
3. Selecione +Adicionar ou selecione um ponto de extremidade existente que você deseja atualizar.
4. Na janela à direita, selecione o Tipo de ponto de extremidade para o domínio personalizado.
5. No campo Nome do host , especifique o nome que 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 na visualização somente para o ponto de extremidade do Gateway.
7. Copie os seguintes valores e use-os para configurar o DNS:
   • Registo TXT
   • Registo CNAME
8. Ao configurar um ponto de extremidade de gateway, selecione ou desmarque outras opções conforme necessário, incluindo Negociar certificado de cliente ou Vinculação SSL padrão.
9. Selecione Adicionar ou selecione Atualizar para um ponto de extremidade existente.
10. Selecione Guardar.

Nota

O processo de atribuição do certificado pode levar 15 minutos ou mais, dependendo do tamanho da implantação. A camada de desenvolvedor tem tempo de inatividade, enquanto as camadas Básica e Superior não.

Configuração do 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.

Nota

O certificado gratuito é emitido pela DigiCert. Para alguns domínios, você deve permitir explicitamente o DigiCert como um emissor de certificado criando um registro de domínio CAA com o valor: 0 issue digicert.com.

Registo CNAME

Configure um registro CNAME que aponte do seu nome de domínio personalizado (por exemplo, api.contoso.com) para o nome de 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 caso o endereço IP mude. Para obter mais informações, consulte Endereços IP do Gerenciamento de API do Azure e as Perguntas frequentes sobre Gerenciamento de API.

Nota

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 registros CNAME, consulte a documentação fornecida pelo seu registrador ou IETF Domain Names - Implementation and Specification.

Atenção

Quando você usa o certificado gerenciado gratuito e configura um registro CNAME com seu provedor de DNS, certifique-se de que ele seja resolvido para o nome de host do serviço de Gerenciamento de API padrão (<apim-service-name>.azure-api.net). Atualmente, o Gerenciamento de API não renova automaticamente o certificado se o registro CNAME não resolver para o nome de host padrão do Gerenciamento de API. Por exemplo, se você estiver usando o certificado gerenciado gratuito e usar a Cloudflare como seu provedor de DNS, verifique se o proxy DNS não está habilitado no registro CNAME.

Registo TXT

Ao habilitar o certificado gerenciado gratuito para 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 sua instância de 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 Get Domain Ownership Identifier .

Como o servidor proxy do Gerenciamento de API responde com certificados SSL no handshake 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 de servidor, dependendo da solicitação do cliente.

Clientes que chamam com o cabeçalho SNI (Indicação de Nome do Servidor)

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

• 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 SNI, o Gerenciamento de API responde com o certificado de servidor apropriado.

Clientes que ligam sem cabeçalho SNI

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

• Se o serviço tiver apenas um domínio personalizado configurado para o Gateway, o certificado padrão será o certificado emitido para o domínio personalizado do Gateway.

• Se o serviço tiver configurado vários domínios personalizados para Gateway (suportados nas camadas Developer 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 Vinculação SSL padrão.

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

Suporte para solicitação PUT/POST com grande carga útil

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

Se a propriedade estiver definida como true, o certificado do cliente será solicitado no momento da conexão SSL/TLS, antes de qualquer troca de solicitação HTTP. Como a configuração se aplica no nível de nome de 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 (suportados apenas na camada Premium ).

Próximos passos

Atualize e dimensione seu serviço