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

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.

Personnalisée

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.

Key Vault

Nous vous recommandons d’utiliser Azure Key Vault pour gérer vos certificats et de les configurer sur autorenew.

Si vous utilisez Azure Key Vault pour gérer un certificat TLS de domaine personnalisé, assurez-vous que le certificat est inséré dans Key Vault en tant que certificat, et non en tant que secret.

Attention

Lorsque vous utilisez un certificat de coffre de clés dans Gestion des API, veillez à ne pas supprimer le certificat, le coffre de clés ou l’identité managée utilisée pour accéder au coffre de clés.

Pour extraire un certificat TLS/SSL, le service Gestion des API doit disposer des autorisations nécessaires pour répertorier et obtenir les secrets sur l’Azure Key Vault contenant le certificat.

• Lorsque vous utilisez le portail Azure pour importer le certificat, toutes les étapes de configuration nécessaires sont effectuées automatiquement.

• Lorsque vous utilisez des outils de ligne de commande ou l’API de gestion, ces autorisations doivent être accordées manuellement, en deux étapes :

  1. Sur la page Identités managées de votre instance Gestion des API, activez une identité managée affectée par le système ou par l’utilisateur. Notez l’ID du principal dans cette page.
  2. Attribuez les autorisations à l’identité managée pour accéder au coffre de clés. Suivez la procédure dans la section suivante.

  Configurer l’accès au coffre de clés

  1. Dans le portail, accédez à votre coffre de clés.

  2. Dans le menu de gauche, sélectionnez Configuration de l’accès et notez le modèle d’autorisation configuré.

  3. Selon le modèle d’autorisation, configurez une stratégie d’accès au coffre de clés ou un accès RBAC Azure pour une identité managée Gestion des API.

     Pour ajouter une stratégie d’accès au coffre de clés :
     

     1. Dans le menu de gauche, sélectionnez Stratégies d’accès.
     2. Sur la page Stratégies d’accès, sélectionnez + Créer.
     3. Sous l’onglet Autorisations, sous Autorisations du secret, sélectionnez Get et List, puis sélectionnez Suivant.
     4. Sous l’onglet Principal, sélectionnez Sélectionner le principal, recherchez le nom de ressource de votre identité managée, puis sélectionnez Suivant. Si vous utilisez une identité attribuée par le système, le principal est le nom de votre instance Gestion des API.
     5. Sélectionnez Suivant de nouveau. Sous l’onglet Review + create (Vérifier + créer) , sélectionnez Créer.

     Pour configurer l’accès RBAC Azure :
     

     1. Dans le menu de gauche, sélectionnez Contrôle d’accès (IAM) .
     2. Sur la page Contrôle d’accès (IAM), sélectionnez Ajout de l’attribution de rôle.
     3. Sous l’onglet Rôle, sélectionnez Utilisateur de secrets Key Vault.
     4. Sous l’onglet Membres, sélectionnez Identité managée>+ Sélectionner des membres.
     5. Dans la page Sélectionner l’identité managée, sélectionnez l’identité managée affectée par le système ou une identité managée affectée par l’utilisateur associée à votre instance Gestion des API, puis sélectionnez Sélectionner.
     6. Sélectionnez Vérifier + attribuer.

Si le certificat est défini sur autorenew et que votre niveau Gestion des API comprend un Contrat de niveau de service (c’est-à-dire dans tous les niveaux, sauf le niveau Développeur), Gestion des API sélectionnera automatiquement la version la plus récente, sans temps d’arrêt du service.

Pour plus d’informations, voir Utiliser des identités managées dans Gestion des API.

Managé

Si vous ne souhaitez pas acheter et gérer votre propre certificat, Gestion des API propose un certificat TLS gratuit et géré pour votre domaine. Le certificat est renouvelé automatiquement.

Remarque

Le certificat TLS managé gratuit est en préversion. Actuellement, il n’est pas disponible dans les niveaux de service v2.

Limites

• Ne peut actuellement être utilisé qu’avec le point de terminaison de passerelle de votre service Gestion des API
• Non pris en charge avec la passerelle autohébergée
• Non pris en charge dans les régions Azure suivantes : France Sud et Afrique du Sud Ouest
• Actuellement disponible uniquement dans le cloud Azure
• Ne prend pas en charge les noms de domaine racine (par exemple, contoso.com). Requiert un nom complet tel que api.contoso.com
• Prend uniquement en charge les noms de domaine public
• Peut uniquement être configuré lors de la mise à jour d’une instance Gestion des API existante, et non lors de la création d’une instance

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

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

Personnalisée

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.
10. Sélectionnez Ajouter ou Mettre à jour pour un point de terminaison existant.
11. Sélectionnez Enregistrer.

Key Vault

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 Key Vault, puis Sélectionner.
   1. Sélectionnez Abonnement dans la liste déroulante.
   2. Sélectionnez le Coffre de clés dans la liste déroulante.
   3. Une fois les certificats chargés, sélectionnez le certificat dans la liste déroulante. Cliquez sur Sélectionner.
   4. Dans Identité du client, sélectionnez une identité managée affectée par l’utilisateur ou une identité affectée par le système activée dans l’instance pour accéder au coffre de clés.
7. 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.
8. Sélectionnez Ajouter ou Mettre à jour pour un point de terminaison existant.
9. Sélectionnez Enregistrer.

Managé

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 Géré pour activer un certificat gratuit géré par Gestion des API. Le certificat géré est disponible en préversion pour le point de terminaison de passerelle uniquement.
7. Copiez les valeurs suivantes et utilisez-les pour configurer DNS :
   • Enregistrement TXT
   • Enregistrement CNAME
8. 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.
9. Sélectionnez Ajouter ou Mettre à jour pour un point de terminaison existant.
10. Sélectionnez Enregistrer.

Notes

Le processus d’attribution du certificat peut prendre 15 minutes ou plus, selon la taille du déploiement. Le niveau Développeur a des temps d’arrêt, tandis que les niveaux De base et supérieurs n’en ont pas.

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