Partager via


Configurer un nom de domaine personnalisé pour votre instance Gestion des API Azure

S’APPLIQUE À : tous les niveaux de Gestion des API

Lorsque vous créez une instance du service Gestion des API Azure dans le cloud Azure, Azure lui attribue un sous-domaine azure-api.net (par exemple, apim-service-name.azure-api.net). Toutefois, vous pouvez exposer vos points de terminaison API Management via votre propre nom de domaine personnalisé, par exemple, contoso.com . Cet article explique comment mapper un nom DNS personnalisé existant à des points de terminaison exposés par une instance Gestion des API.

Important

Gestion des API accepte uniquement les demandes dont les valeurs d’en-tête d’hôte correspondant :

  • Nom de domaine par défaut de la passerelle
  • N’importe quel nom de domaine personnalisé configuré de la passerelle

Remarque

Actuellement, les noms de domaine personnalisés ne sont pas pris en charge dans une passerelle d’espace de travail.

Prérequis

  • Une instance APIM. Pour en savoir plus, voir Créer une instance de gestion des API Azure.

  • Un nom de domaine personnalisé qui vous appartient ou à votre organisation. Cet article ne fournit aucune instruction sur la manière de se procurer un nom de domaine personnalisé.

  • (Facultatif) Un certificat valide avec une clé publique et privée (.PFX). Le sujet ou l’autre nom du sujet (SAN) doit correspondre au nom de domaine. Cela permet à l’instance de Gestion des API d’exposer les URL de manière sécurisée sur TLS.

    Voir Options de certificat de domaine.

  • Des enregistrements DNS hébergés sur un serveur DNS pour mapper le nom de domaine personnalisé au nom de domaine par défaut de votre instance Gestion des API. Cette rubrique ne fournit aucune instruction sur l’hébergement des enregistrements DNS.

    Pour plus d’informations sur les enregistrements requis, voir Configuration DNS plus loin dans cet article.

Points de terminaison pour les domaines personnalisés

Il existe plusieurs points de terminaison Gestion des API auxquels vous pouvez attribuer un nom de domaine personnalisé. Actuellement, les points de terminaison disponibles sont les suivants :

Point de terminaison Default
Passerelle La valeur par défaut est <apim-service-name>.azure-api.net. La passerelle est le seul point de terminaison pouvant être configuré dans le niveau Consommation.

La configuration du point de terminaison de passerelle par défaut reste disponible après l’ajout d’un domaine de passerelle personnalisé.
Portail des développeurs La valeur par défaut est <apim-service-name>.developer.azure-api.net.
Gestion La valeur par défaut est <apim-service-name>.management.azure-api.net.
API de configuration (v2) La valeur par défaut est <apim-service-name>.configuration.azure-api.net.
SCM La valeur par défaut est <apim-service-name>.scm.azure-api.net.

Considérations

  • Vous pouvez mettre à jour n’importe lequel des points de terminaison pris en charge dans votre niveau de service. En règle générale, les clients mettent à jour les points de terminaison Passerelle (cette URL est utilisée pour appeler les API exposées via Gestion des API) et Portail des développeurs (URL du portail des développeurs).
  • Le point de terminaison de passerelle par défaut est également disponible après avoir configuré un nom de domaine de passerelle personnalisé et ne peut pas être supprimé. Pour les autres points de terminaison Gestion des API (tels que le Portail des développeurs) que vous configurez avec un nom de domaine personnalisé, le point de terminaison par défaut n’est plus disponible.
  • Seuls les propriétaires d’instance API Management peuvent utiliser des points de terminaison Gestion et SCM en interne. Ces points de terminaison sont moins souvent affectés à un nom de domaine personnalisé.
  • Toutefois, les niveaux Premium et Developerprennent en charge la définition de plusieurs noms d’hôte pour le point de terminaison Passerelle.
  • Les noms de domaine génériques, *.contoso.com par exemple, sont pris en charge à tous les niveaux, à l’exception du niveau Consommation. Un certificat spécifique du sous-domaine (par exemple, api.contoso.com) est prioritaire sur un certificat générique (*.contoso.com) pour les requêtes vers api.contoso.com.

Options de certificat de domaine

Gestion des API prend en charge les certificats TLS personnalisés ou les certificats importés à partir d’Azure Key Vault. Vous pouvez également activer un certificat géré gratuit.

Avertissement

Si vous avez besoin d’un épinglage de certificat, veuillez utiliser un nom de domaine personnalisé et un certificat personnalisé ou Key Vault, et non le certificat par défaut ou le certificat géré gratuit. Nous vous déconseillons de prendre une dépendance dure sur un certificat que vous ne gérez pas.

Si vous disposez déjà d’un certificat privé provenant d’un fournisseur tiers, vous pouvez le charger dans votre instance Gestion des API. Il doit répondre aux exigences suivantes. (Si vous activez le certificat gratuit géré par Gestion des API, il répond déjà à ces exigences.)

  • Être exporté en tant que fichier PFX, chiffré par Triple-DES et protégé par un mot de passe facultatif.
  • Contenir une clé privée d’au moins 2048 bits de long
  • Contient tous les certificats intermédiaires et le certificat racine dans la chaîne de certificats.

Définir un nom de domaine personnalisé (portail)

Choisissez les étapes en fonction du certificat de domaine que vous souhaitez utiliser.

  1. Accédez à votre instance APIM dans le portail Azure.
  2. Dans le volet de navigation de gauche, sélectionnez Domaines personnalisés.
  3. Sélectionnez +Ajouter ou sélectionnez un point de terminaison existant que vous souhaitez mettre à jour.
  4. Dans la fenêtre de droite, sélectionnez le Type de point de terminaison pour le domaine personnalisé.
  5. Dans la zone Nom d’hôte, spécifiez le nom que vous souhaitez utiliser. Par exemple : api.contoso.com.
  6. Sous Certificat, sélectionnez Personnalisé.
  7. Sélectionnez Fichier de certificat pour sélectionner et charger un certificat.
  8. Chargez un fichier .PFX valide et fournissez son Mot de passe si le certificat est protégé par un mot de passe.
  9. Lors de la configuration d’un point de terminaison de passerelle, sélectionnez ou désélectionnez d’autres options si nécessaire, notamment Négocier le certificat client ou Liaison SSL par défaut. Configurer le domaine de la passerelle avec un certificat personnalisé
  10. Sélectionnez Ajouter ou Mettre à jour pour un point de terminaison existant.
  11. Sélectionnez Enregistrer.

Configuration DNS

  • Configurez un enregistrement CNAME pour votre domaine personnalisé.
  • Si vous utilisez le certificat gratuit et géré de Gestion des API, configurez également un enregistrement TXT pour établir votre propriété du domaine.

Notes

Le certificat gratuit est émis par DigiCert. Pour certains domaines, vous devez autoriser explicitement DigiCert comme émetteur de certificat en créant un enregistrement de domaine CAA avec la valeur : 0 issue digicert.com.

Enregistrement CNAME

Configurez un enregistrement CNAME qui pointe de votre nom de domaine personnalisé (par exemple, api.contoso.com) vers le nom d’hôte de votre service Gestion des API (par exemple, <apim-service-name>.azure-api.net). Un enregistrement CNAME est plus stable qu’un enregistrement A en cas de modification de l’adresse IP. Pour plus d’informations, consultez Adresses IP de Gestion des API Azure et la FAQ relative à Gestion des API.

Notes

Certains registrars de domaines vous permettent uniquement de mapper des sous-domaines à l’aide d’un enregistrement CNAME, comme www.contoso.com, et non des noms racines, comme contoso.com. Pour plus d’informations sur les enregistrements CNAME, consultez la documentation fournie par votre registrar ou le document Domain Names – Implementation and Specification d’IETF.

Attention

Lorsque vous utilisez le certificat managé gratuit et que vous configurez un enregistrement CNAME avec votre fournisseur DNS, assurez-vous qu’il correspond au nom d’hôte du service Gestion des API par défaut (<apim-service-name>.azure-api.net). Actuellement, Gestion des API ne renouvelle pas automatiquement le certificat si l’enregistrement CNAME ne correspond pas au nom d’hôte par défaut Gestion des API. Par exemple, si vous utilisez le certificat managé gratuit et que vous utilisez Cloudflare comme fournisseur DNS, assurez-vous que le proxy DNS n’est pas activé sur l’enregistrement CNAME.

Enregistrement TXT

Lorsque vous activez le certificat géré gratuit pour Gestion des API, configurez également un enregistrement TXT dans votre zone DNS pour établir votre propriété du nom de domaine.

  • Le nom de l’enregistrement est votre nom de domaine personnalisé avec le préfixe apimuid. Exemple : apimuid.api.contoso.com.
  • La valeur est un identificateur de propriété de domaine fourni par votre instance Gestion des API.

Lorsque vous utilisez le portail pour configurer le certificat géré gratuit pour votre domaine personnalisé, le nom et la valeur de l’enregistrement TXT nécessaire s’affichent automatiquement.

Vous pouvez également obtenir un identificateur de propriété de domaine en appelant l’API REST Obtenir l’identificateur de propriété de domaine.

Réponse du serveur proxy Gestion des API avec les certificats SSL durant l’établissement d’une liaison TLS

Lorsque vous configurez un domaine personnalisé pour le point de terminaison de passerelle, vous pouvez définir des propriétés supplémentaires qui déterminent la façon dont Gestion des API répond avec un certificat de serveur, en fonction de la requête du client.

Clients appelant avec l’en-tête Indication du nom du serveur (SNI)

Si vous avez un ou plusieurs domaines personnalisés configurés pour le point de terminaison de passerelle, Gestion des API peut répondre aux requêtes HTTPS à partir de l’un ou l’autre :

  • Domaine personnalisé (par exemple, contoso.com)
  • Domaine par défaut (par exemple, apim-service-name.azure-api.net).

En fonction des informations contenues dans l’en-tête SNI, API Management répond avec le certificat de serveur approprié.

Clients appelant sans l’en-tête SNI

Si vous utilisez un client qui n’envoie pas l’en-tête SNI, API Management crée des réponses en fonction de la logique suivante :

  • Si le service n’a qu’un seul domaine personnalisé configuré pour la passerelle, le certificat par défaut est le certificat émis pour le domaine personnalisé de la passerelle.

  • Si le service a configuré plusieurs domaines personnalisés pour la passerelle (pris en charge dans les niveaux Développeur et Premium), vous pouvez désigner le certificat par défaut en définissant la propriété defaultSslBinding sur true ("defaultSslBinding":"true"). Dans le portail, cochez la case Liaison SSL par défaut.

    Si vous ne définissez pas la propriété, le certificat par défaut est le certificat émis pour le domaine de passerelle par défaut hébergé sur *.azure-api.net.

Prise en charge pour la requête PUT/POST avec une charge utile de grande taille

Le serveur proxy de Gestion des API prend en charge les requêtes avec des charges utiles de grande taille (>40 ko) lors de l’utilisation de certificats côté client dans le protocole HTTPS. Pour éviter que la requête du serveur ne gèle, vous pouvez définir la propriété negotiateClientCertificate sur true ("negotiateClientCertificate": "true") sur le nom d’hôte de la passerelle. Dans le portail, cochez la case Négocier le certificat client.

Si la propriété est définie sur true, le certificat client est demandé au moment de la connexion SSL/TLS, avant tout échange de requête HTTP. Étant donné que le paramètre s’applique au niveau du nom d’hôte de la passerelle, toutes les demandes de connexion demandent le certificat client. Vous pouvez contourner cette limitation et configurer jusqu’à 20 domaines personnalisés pour la passerelle (uniquement pris en charge dans le niveau Premium).

Étapes suivantes

Mettre à niveau votre service et le mettre à l’échelle